Wortal SDK for GameMaker

설치하기

GameMaker Marketplace에서 Wortal 확장 프로그램 설치하기
Included Files -> wortal_index.html로 이동하여 JS 파일의 경로를 게임 파일로 대체하세요
- GameMaker 빌드 결과물인 .zip 아카이브 압축 풀기 - index.html을 열고 화면 하단 부근에서 아래 줄을 찾는다: <script type="text/javascript" src="html5game/yourgame.js?DBDYB=830673173"></script></script>.

- 위 행을 복사하여 저장하기 - wortal_index.html을 열고, 화면 하단에 있는 다음 줄을 찾습니다:  - C 단계에서 복사한 코드로 해당 행을 대체합니다

Game Options -> HTML5 -> Advanced -> Included file as index.html 순으로 열고 이 옵션을 wortal_index.html로 변경합니다

사용방법

// 플레이어가 레벨을 달성.
wortal_ads_show_interstitial("next", "NextLevel");

// 플레이어가 게임을 일시 중지했습니다.
wortal_ads_show_interstitial("pause", "PausedGame");

// 플레이어가 인앱 결제 페이지에 접속합니다.
wortal_ads_show_interstitial("browse", "BrowseShop");

리워드 광고는 플레이어가 동영상 광고를 끝까지 시청하는 등의 조건을 충족할 경우 보상을 제공하는 광고 유형입니다. 반드시 플레이어에게 알리고 허락을 받은 후 표시해야 합니다.

// 이 예시에서는 광고 조건 달성 여부와 상관없이 게임이 진행됩니다.
// 예: 플레이어는 광고를 시청하여 보너스 코인을 획득할 수 있지만, 그 결과와 상관없이 게임은 계속 진행됩니다.
wortal_ads_show_rewarded("BonusCoins");

// 이 예시에서는 광고 조건 달성 여부와 관련하여 게임이 진행됩니다.
// 예: 게임오버 시 플레이어는 광고를 시청하여 부활할 수 있지만, 광고를 건너뛰면 해당 레벨을 잃게 됩니다.
wortal_ads_show_rewarded("ReviveAndContinue");

참고: 플레이어는 adViewed 콜백을 통해서만 보상을 받을 수 있습니다.

애널리틱스

API 레퍼런스

Wortal의 애널리틱스 API를 활용하여 게임 이벤트를 추적하고 플레이어의 게임 내 활동을 파악할 수 있습니다. 이 데이터는 Wortal의 대시보드에서 확인할 수 있습니다.

// 레벨 시작을 기록합니다.
wortal_analytics_log_level_start("Level 3");

// 레벨의 끝을 기록합니다. 이름이 일치하면 게임 시간을 기록한다.
// logLevelStart()의 마지막 호출명
wortal_analytics_log_level_end("Level 3", "100", 1);

// 플레이어의 게임 내 선택 행동을 기록합니다. 게임의 밸런스를 맞추는 데 도움이 됩니다.
// 그리고 플레이어가 많이 이용하는 콘텐츠를 파악할 수 있습니다.
wortal_analytics_log_game_choice("Character", "Blue");

업적

API 레퍼런스

Achievements API는 플레이어의 게임 내 진행 상황을 추적하는 데 사용됩니다. 특정 작업을 완료하거나 특정 마일스톤에 도달하면 잠금 해제할 수 있습니다.

// 업적 잠금 해제하기.
wortal_achievements_unlock_async("achievementID");

// 플레이어의 업적 진행 상황 파악하기
wortal_achievements_get_async();

컨텍스트

API 레퍼런스

컨텍스트 API는 플레이어끼리 연결하여 게임 섹션 참여, 콘텐츠 공유, 메시지 교환 등에 활용할 수 있습니다.

// 친구를 게임에 초대합니다. 
payload = {
    image: "data:base64image",
    text: "Invite text",
    cta: "Play",
    data: { exampleData: "yourData" },
}

wortal_context_invite_async(json_stringify(payload));

// 이 게임의 활동을 친구들과 공유하세요.
payload = {
    image: "data:base64image",
    text: "Share text",
    cta: "Play",
    data: { exampleData: "yourData" },
}

wortal_context_share_async(json_stringify(payload));

인앱결제

API 레퍼런스

인앱 결제(IAP) API는 플랫폼에서 게임 내 트랜잭션이 발생할 때 사용됩니다. 이 프로세스는 플레이 중인 플랫폼에 따라 다르지만, IP는 동일합니다.

// 플레이어가 구매할 수 있는 아이템 목록 확인.
wortal_iap_get_catalog_async();

// 아이템 구매하기.
purchaseConfig = {
    productID: "my_product_123",
}

wortal_iap_make_purchase_async(json_stringify(purchaseConfig));

리더보드

API 레퍼런스

리더보드 API를 활용하면 플랫폼의 리더보드 기능에 접근할 수 있습니다. 플레이어들의 점수를 추적하고 순위를 매길 수 있습니다.

// 상위 10위 안에 든 리더보드를 획득할 수 있다.
wortal_leaderboard_get_entries_async("global", 10, 0);

// 플레이어의 점수를 리더보드에 추가합니다.
wortal_leaderboard_send_entry_async("global", 100, "details");

알림

API 레퍼런스

Notifications API는 플레이어에게 알림을 보내는 데 사용됩니다. 플레이어에게 게임 내 이벤트를 알리거나 다시 플레이하도록 유도하는 데 사용할 수 있습니다.

// 플레이어에게 보낼 알림을 예약합니다.
payload = {
    title: "Your energy is full!",
    body: "Come back and play again.",
    mediaURL: "https://example.com/image.png",
    label: "resources-full",
    scheduleInterval: 300 // 5 minutes
}

wortal_notifications_schedule_async(json_stringify(payload));

// 예약된 알림을 취소합니다.
wortal_notifications_cancel_async("notification-id-123");

플레이어

API 레퍼런스

현재 플레이어에 대한 자세한 내용은 Player API에서 확인할 수 있습니다

// 플레이어의 이름을 가져옵니다.
wortal_player_get_name();

// 플레이어의 친구 중 게임을 해본 적이 있는 사람들의 목록을 가져옵니다.
payload = {
    filter: "ALL",
    size: 20,
    hoursSinceInvitation: 4,
}

wortal_player_get_connected_players_async(json_stringify(payload));

세션

API 레퍼런스

현재 세션 상태에 대한 자세한 내용은 Session API에서 확인할 수 있습니다.

// 게임이 시작된 진입점을 얻는다.
wortal_session_get_entry_point_async();

통계

API 레퍼런스

Stats API는 플레이어의 게임 내 통계를 추적하는 데 사용됩니다.

// 선수의 통계 정보를 게시한다.
wortal_stats_post_async("level 1", 100);

// 특정 레벨에 대한 플레이어의 통계를 얻는다.
wortal_stats_get_async("level 1");

토너먼트

API 레퍼런스

Tournament API는 게임의 토너먼트를 생성하고 관리하는 데 사용됩니다.

// 토너먼트 생성하기.
const payload = {
    initialScore: 100,
    config: {
        title: "Level 1 Tournament",
    },
    data: {
        level: 1,
    },
};

wortal_tournament_create_async(json_stringify(payload));

// 토너먼트에서 점수를 기록한다.
wortal_tournament_post_score_async(200);

Wortal 콜백

SDK는 콜백 이벤트가 있는 많은 비동기 호출을 사용합니다. 이 함수들은 the _async 접미사(the _async suffix)로 표시되어 있습니다. 이러한 콜백을 수신하고 Async - Social 이벤트에서 적절히 처리해야 합니다. 콜백 이벤트는 다음과 같은 SDK 정의 속성을 가진 맵으로 반환됩니다:

id: "wortal_callback", // Wortal의 콜백은 항상 동일하다.
event, // 콜백의 이벤트 이름.
success, // 에러 플래그. 0"은 오류가 발생했음을 의미하며, "1"은 호출이 성공했음을 의미한다.
payload, // 선택적 리턴 데이터. 에러가 발생하지 않은 경우에만 존재하며, 그 유형은 호출에 따라 다르다.
error // 에러가 발생했을 경우, 에러가 포함된 JSON 문자열.

광고 콜백 핸들러의 예시:

var ID = async_load[? "id"];
if (ID != undefined) {
    if (ID == "wortal_callback") {
        switch (async_load[? "event"]) {
            case "ADS_BEFORE_AD_CALLBACK":
                // Pause game and audio here.
                break;
            case "ADS_AFTER_AD_CALLBACK":
                // Resume game and audio here.
                break;
            case "ADS_AD_DISMISSED_CALLBACK":
                // Do not reward the player - ad was skipped.
                break;
            case "ADS_AD_VIEWED_CALLBACK":
                // Reward player for watching the ad.
                break;
        }
    }
}

모든 콜백 이벤트와 그 페이로드 목록:

INITIALIZE_CALLBACK // Void
START_GAME_CALLBACK // Void
ON_PAUSE_CALLBACK // Void
PERFORM_HAPTIC_FEEDBACK_CALLBACK // Void

ADS_BEFORE_AD_CALLBACK // Void
ADS_AFTER_AD_CALLBACK // Void
ADS_AD_DISMISSED_CALLBACK // Void
ADS_AD_VIEWED_CALLBACK // Void
ADS_NO_FILL_CALLBACK // Void

CONTEXT_CHOOSE_CALLBACK // Void
CONTEXT_CREATE_CALLBACK // Void
CONTEXT_SWITCH_CALLBACK // Void
CONTEXT_INVITE_CALLBACK // Void
CONTEXT_SHARE_CALLBACK // Number
CONTEXT_SHARE_LINK_CALLBACK // Void
CONTEXT_UPDATE_CALLBACK // Void

IAP_GET_CATALOG_CALLBACK // Product[]
IAP_GET_PURCHASES_CALLBACK // Purchase[]
IAP_MAKE_PURCHASE_CALLBACK // Purchase
IAP_CONSUME_PURCHASE_CALLBACK // Void

LEADERBOARD_GET_LEADERBOARD_CALLBACK // Leaderboard
LEADERBOARD_SEND_ENTRY_CALLBACK // LeaderboardEntry
LEADERBOARD_GET_ENTRIES_CALLBACK // LeaderboardEntry[]
LEADERBOARD_GET_PLAYER_ENTRY_CALLBACK // LeaderboardEntry
LEADERBOARD_GET_ENTRY_COUNT_CALLBACK // Number
LEADERBOARD_GET_CONNECTED_PLAYERS_ENTRIES_CALLBACK // LeaderboardEntry[]

NOTIFICATIONS_SCHEDULE_CALLBACK // NotificationScheduleResult
NOTIFICATIONS_GET_HISTORY_CALLBACK // ScheduledNotification[]
NOTIFICATIONS_CANCEL_CALLBACK // Boolean
NOTIFICATIONS_CANCEL_ALL_CALLBACK // Boolean

PLAYER_GET_DATA_CALLBACK // Developer-defined object
PLAYER_SET_DATA_CALLBACK // Void
PLAYER_GET_CONNECTED_PLAYERS_CALLBACK // Player[]
PLAYER_GET_SIGNED_PLAYER_INFO_CALLBACK // Object with id and signature
PLAYER_GET_ASID_CALLBACK // String
PLAYER_GET_SIGNED_ASID_CALLBACK // Object with id and signature
PLAYER_CAN_SUBSCRIBE_BOT_CALLBACK // Boolean
PLAYER_SUBSCRIBE_BOT_CALLBACK // Void

SESSION_GET_ENTRY_POINT_CALLBACK // String
SESSION_ON_ORIENTATION_CHANGE_CALLBACK // Orientation
SESSION_SWITCH_GAME_CALLBACK // Void

TOURNAMENT_GET_CURRENT_CALLBACK // Tournament
TOURNAMENT_GET_ALL_CALLBACK // Tournament[]
TOURNAMENT_POST_SCORE_CALLBACK // Void
TOURNAMENT_CREATE_CALLBACK // Tournament
TOURNAMENT_SHARE_CALLBACK // Void
TOURNAMENT_JOIN_CALLBACK // Void

데모 프로젝트

SDK 호출 구현 예제가 포함된 데모 패키지는 여기에서 확인할 수 있습니다.