주요 콘텐츠로 건너뛰기

Unity SDK 참조

Android 및 iOS 앱 모두에서 Checkout을 사용할 수 있도록 해주는 Aghanim Unity SDK입니다.

Android. 기본 브라우저
Android. 기본 브라우저

Android. 기본 브라우저

통합

SDK를 통합하려면 사전 요구 사항 및 통합 → Unity의 자세한 지침을 참조하세요.

메소드 참조

SDK는 Aghanim 엔티티를 통해 Aghanim API에 직접 액세스할 수 있게 합니다.

주문 가져오기

주문 세부 정보를 얻으려면 GetOrder 메소드를 사용하세요.

Aghanim.GetOrder(
    orderId: "order_123",
    onSuccess: (order) => {
        Debug.Log($"Order ID: {order.id}");
        Debug.Log($"Player ID: {order.player_id}");
        Debug.Log($"Total price: {order.price_minor_unit} {order.currency}");
    },
    onError: (error) => {
        Debug.LogError($"Failed to get order: {error}");
    }
);
파라미터형식필수 여부설명
orderId문자열예주문에 대한 고유 ID입니다.
onSuccessAction<OrderRead>오류가 없는 경우 예성공적인 결과가 있을 때 호출되는 콜백입니다.
onErrorAction<string>성공이 없는 경우 예실패한 결과가 있을 때 호출되는 콜백입니다.

소비되지 않은 주문 가져오기

결제되었으나 아직 제공되지 않은 주문을 알기 위해 GetUnconsumedOrders 메소드를 사용하세요.

Aghanim.GetUnconsumedOrders(
    onSuccess: (response) =>
    {
        // Player has paid but not granted items from orders
        var unconsumedOrderIds = response.Orders;
        // TODO: Save order IDs for further consuming and granting
    },
    onError: (debugMessage) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to get unconsumed orders: {debugMessage}");
        // TODO: Handle error
    }
);
파라미터형식필수 여부설명
onSuccessAction<UnconsumedOrdersResponse>오류가 없는 경우 예Callback that is invoked on successful result. Use response.Orders to access the array of order IDs.
onErrorAction<string>성공이 없는 경우 예실패한 결과가 있을 때 호출되는 콜백입니다.

사용 시점

GetUnconsumedOrders 및 ConsumeOrder는 전용 서버가 없는(서버리스) 게임을 위해 설계되었습니다. 클라이언트 측에서만 아이템 지급을 전적으로 처리할 수 있습니다.

게임에 서버가 있다면 item.add webhook을 대신 사용하세요. 이 webhook을 사용하면 서버가 아이템 지급을 직접 제어할 수 있습니다. 통합 가이드의 게임 서버 측에서 결제 후 이벤트 처리를 참조하세요.

GetUnconsumedOrders를 호출해야 하는 시점은 사용하는 실행 모드에 따라 달라집니다:

기본 브라우저, 인앱 브라우저, Native UI(Android)를 사용하는 플랫폼별 커스텀

이러한 모드에서는 표준 Unity 콜백 OnApplicationFocus 및 OnApplicationPause를 구독하세요. 이 콜백은 플레이어가 결제를 완료한 뒤 앱으로 돌아올 때 실행됩니다:

private void OnApplicationFocus(bool hasFocus)
{
    if (hasFocus)
    {
        CheckUnconsumedOrders();
    }
}

private void OnApplicationPause(bool isPaused)
{
    if (!isPaused)
    {
        CheckUnconsumedOrders();
    }
}

private void CheckUnconsumedOrders()
{
    Aghanim.GetUnconsumedOrders(
        onSuccess: (response) =>
        {
            foreach (var orderId in response.Orders)
            {
                ConsumeAndGrantOrder(orderId);
            }
        },
        onError: (debugMessage) =>
        {
            Debug.LogError($"Failed to get unconsumed orders: {debugMessage}");
        }
    );
}

인앱 브라우저(iOS)

iOS에서는 OnApplicationFocus / OnApplicationPause 외에도, 플레이어가 인앱 브라우저를 닫는 정확한 순간에 onViewClosed 콜백이 실행됩니다:

var launchMode = new LaunchMode(
    android: AndroidLaunchMode.InAppBrowser(),
    ios: IOSLaunchMode.InAppBrowser(
        onViewClosed: (e) =>
        {
            // Earliest point to check order status on iOS
            CheckUnconsumedOrders();
        }
    )
);

결제된 주문 소비

SDK에 주문을 통해 구매한 아이템이 제공된 것을 인정하기 위해 ConsumeOrder 메소드를 사용하세요.

Aghanim.ConsumeOrder(
    orderId: orderId,
    onSuccess: () =>
    {
        // Paid order is marked as consumed
        Debug.Log($"Order consumed: {orderId}");
        // TODO: Grant items in order to player
    },
    onError: (debugMessage) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to consume order: {debugMessage}");
        // TODO: Handle error
    }
);
파라미터형식필수 여부설명
orderId문자열예주문에 대한 고유 ID입니다.
onSuccessAction오류가 없는 경우 예성공적인 결과가 있을 때 호출되는 콜백입니다.
onErrorAction<string>성공이 없는 경우 예실패한 결과가 있을 때 호출되는 콜백입니다.

사용 시점

미소비 주문을 가져온 뒤 ConsumeOrder를 호출하여 지급 완료로 표시하세요. 이렇게 하면 다음 GetUnconsumedOrders 호출에서 동일한 주문이 다시 지급되는 것을 방지할 수 있습니다.

private void ConsumeAndGrantOrder(string orderId)
{
    Aghanim.ConsumeOrder(
        orderId: orderId,
        onSuccess: () =>
        {
            Debug.Log($"Order consumed: {orderId}");
            // TODO: Grant items to player
        },
        onError: (debugMessage) =>
        {
            Debug.LogError($"Failed to consume order: {debugMessage}");
        }
    );
}

플레이어 ID 설정

현재 SDK 인스턴스에 대해 일회성으로 플레이어 ID를 설정하려면 SetPlayerId 메서드를 사용하세요. SDK는 이후 호출되는 모든 메서드에 이 ID를 사용합니다.

Aghanim.SetPlayerId(playerId);
파라미터형식필수 여부설명
playerId문자열예플레이어에 대한 고유 ID입니다.

아이템 가져오기

현지화된 가격으로 아이템을 가져오려면 GetItems 메서드를 사용하세요. 이 메서드는 플레이어의 지역에 따라 현지화된 가격이 적용된 SKU Management → Items에서 생성된 아이템을 반환합니다.

Aghanim.GetItems(
    skus: new List<string> { "your-item-sku" },
    onSuccess: (items) =>
    {
        foreach (var item in items)
        {
            // Use item.Name, item.Price.Display, item.ImageUrl to populate your store
            Debug.Log($"{item.Name}: {item.Price.Display}");
        }
    },
    onError: (error) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to get items: {error}");
        // TODO: Handle error
    }
);
파라미터형식필수 여부설명
skusList<string>예가져올 아이템 sku 목록(최대 50개).
localeLocale아니요가격 형식을 지정하기 위한 Locale. 지원되는 로케일의 전체 목록은 Checkout → Locales에서 확인하세요.
onSuccessAction<Item[]>오류가 없으면 예성공 결과 시 호출되는 콜백입니다.
onErrorAction<string>성공이 아니면 예실패 결과 시 호출되는 콜백입니다.

Checkout 아이템 생성

아이템 표현을 생성하려면 CheckoutItem 메소드를 사용하세요. 아이템은 SKU 관리 → 아이템에 이미 생성되어 있어야 합니다.

var items = new List<CheckoutItem>
{
    new CheckoutItem("CRS-82500")
};
파라미터형식필수 여부설명
skustring예대시보드에서 아이템 SKU.
namestring아니요대시보드에서 아이템 이름.
descriptionstring아니요대시보드에서 아이템 설명.
imageUrl문자열아니요대시보드에서 아이템 이미지 URL.
quantityint아니요아이템 수량.

리디렉션 행동 생성

결제가 성공적으로 완료된 후 플레이어 리디렉션 동작을 선택하려면 RedirectSettings 메소드를 사용하세요.

플레이어가 결제를 완료하면 SDK는 즉시 backToGameUrl에서의 딥 링크로 리디렉션합니다.

var redirectSettings = new RedirectSettings(
    mode: RedirectMode.Immediate
);
파라미터유형필수 여부설명
modeRedirectMode예리디렉션 모드. 가능한 값: Immediate, Delayed, NoRedirect.
delaySecondsintDelayed인 경우 예초 단위의 지연. Delayed 모드의 기본 값은 5입니다.

UI 설정 생성

Checkout의 외관 모드를 설정하려면 UiSettings 메서드를 사용하세요.

SDK는 시스템 설정에 따라 적절한 외관 모드를 자동으로 감지하고 적용합니다.

var uiSettings = new UiSettings(
    mode: UiMode.Auto
);
파라미터유형필수 여부설명
modeUiMode예UI 모드. 가능한 값: Auto, Dark, Light.

Checkout 파라미터 생성

Checkout 파라미터를 생성하기 위해, 플레이어가 결제 양식에서 볼 수 있는 표현을 CheckoutParams 메소드를 사용하여 만드세요.

var checkoutParams = new CheckoutParams(
    items: items,
    backToGameUrl: "https://<YOUR_DOMAIN>/checkout-complete"
);
파라미터유형필수 여부설명
itemsList<CheckoutItem>예아이템 목록입니다.
metadataDictionary<string, string>아니요추적을 위한 "키-값" 쌍으로 구성된 메타데이터입니다.
priceTemplateId문자열아니요가격 포인트 가져오기에서 현지화된 가격을 위한 가격 템플릿 ID입니다.
locale문자열아니요아이템 이름 및 설명 현지화를 위한 로케일입니다. 지원되는 locale의 전체 목록은 Checkout → Locales에서 확인하세요.
backToGameUrl문자열아니요앱으로 플레이어를 되돌리는 깊은 링크 URL입니다.
redirectSettingsRedirectSettings아니요결제 후 리디렉션 행동입니다.
uiSettingsUiSettings아니요Checkout 외관 설정.

Checkout 실행 모드 사용

결제 양식을 실행하려면 LaunchMode 엔티티를 사용하세요.

Android 및 iOS의 경우, 인앱 브라우저 실행 모드는 Android Custom Tabs 및 iOS SFSafariViewController를 통해 끊김 없는 플레이어 경험을 제공합니다.

LaunchMode.InternalBrowser

Checkout 시작

Checkout 프로세스를 시작하려면 StartCheckout 메서드를 사용하세요. 이 메서드는 제공된 Checkout 파라미터로 주문을 생성하고 Checkout UI를 엽니다. 성공 시 Order ID를 받습니다. 실패 시 디버그 정보가 포함된 오류를 받습니다.

Android 및 iOS에서 인앱 브라우저 실행 모드는 Android Custom Tabs 및 iOS SFSafariViewController를 통해 매끄러운 플레이어 경험을 제공합니다.

Aghanim.StartCheckout(
    checkoutParams,
    LaunchMode.InternalBrowser,
    onSuccess: (orderId) =>
    {
        // Order is created and checkout has launched successfully
        // TODO: Save order ID for further granting or tracking
    },
    onError: (error) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to launch Checkout: {error}");
        // TODO: Show user-friendly error message to player
    }
);
파라미터형식필수 여부설명
checkoutParamsCheckoutParams예Checkout 구성.
launchModeLaunchMode예Checkout의 실행 모드.
onSuccessAction<string>예Checkout 실행에 성공했을 때 주문 ID와 함께 호출되는 콜백입니다.
onErrorAction<string>예Checkout 실행에 실패했을 때 오류 메시지와 함께 호출되는 콜백입니다.

Checkout 표시

기존 주문에 대해 Checkout UI를 표시하려면 PresentCheckout 메서드를 사용하세요. 서버-투-서버 주문 생성으로 얻은 주문 ID가 있거나, 이전에 중단된 checkout을 재개하는 경우에 이를 사용하세요.

Android 및 iOS의 경우 In-app browser 실행 모드는 Android Custom Tabs 및 iOS SFSafariViewController를 통해 끊김 없는 플레이어 경험을 제공합니다.

Aghanim.PresentCheckout(
    orderId,
    LaunchMode.InternalBrowser,
    onSuccess: (orderId) =>
    {
        // Checkout has launched successfully for the existing order
    },
    onError: (error) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to present Checkout: {error}");
        // TODO: Show user-friendly error message to player
    }
);
ParameterTypeRequiredDescription
orderId문자열Yes열 기존 주문의 ID.
launchModeLaunchMode예Checkout의 실행 모드.
onSuccessAction<string>예성공적으로 Checkout을 실행하면 Order ID와 함께 호출되는 콜백입니다.
onErrorAction<string>예Checkout 실행에 실패하면 오류 메시지와 함께 호출되는 콜백입니다.

FAQ

What platforms does your Unity SDK support?

The Unity SDK is available for both iOS and Android.

도움이 필요하세요?
통합팀에 문의하십시오 [email protected]

On this page