跳至主要内容

Android SDK 参考

Aghanim Android SDK 允许您在 Android 应用中使用 Checkout。

Native UI
Native UI

Native UI

集成

要集成 SDK，请查看其先决条件和详细说明，参见集成 → Android。

方法参考

获取未消费的订单

要了解哪些订单已付款但未发放，请使用 getUnconsumed 或 getUnconsumedAsync 方法。

import com.aghanim.android.sdk.common.api.result.ApiResult
import android.util.Log

when (val unconsumedResult = aghanim.orders.getUnconsumed()) {
    is ApiResult.Success -> {
        // Player has paid but not granted items from orders
        val unconsumedOrderIds = unconsumedResult.value
        // TODO: Save order IDs for further consuming and granting
    }

    is ApiResult.Failure -> {
        // Log debug information for troubleshooting
        Log.e("Orders", "Failed to get unconsumed orders: ${unconsumedResult.error}")
        // TODO: Handle error
    }
}

消费已支付订单

要让 SDK 确认您已通过订单向玩家授予商品，请使用 consume 或 consumeAsync 方法。

import com.aghanim.android.sdk.common.api.result.ApiResult
import android.util.Log

when (val consumeResult = aghanim.orders.consume(orderId)) {
    is ApiResult.Success -> {
        // Paid orders are marked as consumed
        Log.d("Orders", "Order $orderId is successfully consumed")
        // TODO: Grant items in order to player
    }

    is ApiResult.Failure -> {
        // Log debug information for troubleshooting
        Log.e("Orders", "Failed to consume order: ${consumeResult.error}")
        // TODO: Handle error
    }
}

设置玩家 ID

要为当前 SDK 实例设置一次玩家 ID，使用 setPlayerId 方法。 SDK 将在所有后续方法调用中使用此 ID。

aghanim.setPlayerId(playerId)
参数类型必填项描述
playerIdstring是玩家的唯一 ID。

获取商品列表

要检索带本地化价格的商品，请使用 items.get 或 items.getAsync 方法。 该方法会返回在 SKU Management → Items 中创建的商品，并根据玩家的地区对价格进行本地化。

import com.aghanim.android.sdk.common.api.result.ApiResult
import android.util.Log

when (val result = aghanim.items.get(
    skus = listOf("your-item-sku"),
)) {
    is ApiResult.Success -> {
        val items = result.value
        items.forEach { item ->
            // Use item.name, item.price.display, item.imageUrl to populate your store
            Log.d("Items", "${item.name}: ${item.price.display}")
        }
    }

    is ApiResult.Failure -> {
        // Log debug information for troubleshooting
        Log.e("Items", "Failed to get items: ${result.error}")
        // TODO: Handle error
    }
}
参数Type必填项描述
skusList<String>是要检索的商品 SKU 列表（最多 50 个）。
区域设置区域设置否用于价格格式化的区域设置。 在 Checkout → Locales 中查看支持的区域设置完整列表。

创建 Checkout 商品

要创建商品表示，请使用 CheckoutItem 方法。 商品应已在 SKU 管理 → 商品 中创建。

import com.aghanim.android.sdk.checkout.core.api.models.CheckoutItem

val checkoutItem = CheckoutItem(
    sku = "CRS-82500"
)
参数Type必填项描述
skustring是来自控制台的商品 SKU。
namestring否来自控制台的商品名称。
descriptionstring否来自控制台的商品描述。
imageUrlstring否来自控制台的商品图片 URL。
quantityint否商品数量。

创建重定向行为

要选择支付成功后重定向玩家的行为，请使用 RedirectSettings 方法。

玩家完成支付后，SDK 会立即重定向到 backToGameUrl 的深链接。

import com.aghanim.android.sdk.common.api.models.order.RedirectSettings
import com.aghanim.android.sdk.common.api.models.order.RedirectMode

val redirectSettings = RedirectSettings(
    mode = RedirectMode.IMMEDIATE
)
参数类型必填项描述
modeRedirectMode是重定向模式。 可能的值：Immediate，Delayed，NoRedirect。
delaySecondsint是如果是 Delayed以秒为单位的延迟。 对于 Delayed 模式，默认为 5。

创建 UI 设置

要设置 Checkout 的外观模式，请使用 UiSettings 方法。

SDK 会根据系统设置自动检测并应用相应的外观模式。

import com.aghanim.android.sdk.checkout.core.api.models.UiSettings
import com.aghanim.android.sdk.checkout.core.api.models.UiMode

val uiSettings = UiSettings(
    mode = UiMode.AUTO
)
参数类型必填项描述
modeUiMode是UI 模式。 可选值：Auto、Dark、Light。

创建 Checkout 参数

要创建 Checkout 参数，玩家在支付表单上看到的表示，请使用 CheckoutParams 方法。

对于本地 UI 启动模式，创建 Checkout 参数较为简单。 由于 Checkout 不使用浏览器启动，无需传递 backToGameUrl。

import com.aghanim.android.sdk.checkout.core.api.models.CheckoutParams
import com.aghanim.android.sdk.common.api.models.common.Locale

val checkoutParams = CheckoutParams(
    items = listOf(checkoutItem),
    customMessage = "Holiday Sale!",
    locale = null
)
参数类型必填项描述
itemsList<CheckoutItem>是商品列表。
metadataMap<string, string>否用于追踪目的的“键值对”结构的元数据。
priceTemplateIdstring否用于本地化的价格模板 ID，参见获取价格点。
区域设置string否适用于商品名称和描述本地化的区域设置。 在 Checkout → Locales 中查看支持的区域设置完整列表。
customMessagestring否Checkout 页面消息。
backToGameUrlstring否返回玩家至应用程序的深层链接 URL。 如未提供则自动生成。
redirectSettingsRedirectSettings否支付后的重定向行为。
uiSettingsUiSettings否Checkout 外观设置。

启动 Checkout

要启动 Checkout 流程，请使用 startCheckout 或 startWebCheckout 方法。 该方法会根据提供的 checkout 参数创建订单并打开 Checkout UI。 返回 ApiResult<String>，其中成功值为订单 ID。

启动模式使用 Native UI ，它完全控制玩家的体验。

import com.aghanim.android.sdk.checkout.ui.api.startCheckout
import com.aghanim.android.sdk.common.api.result.ApiResult
import android.util.Log

when (val result = aghanim.startCheckout(
    context = context,
    checkoutParams = checkoutParams,
)) {
    is ApiResult.Success -> {
        // Order is created and checkout has launched successfully
        val orderId = result.value
        // TODO: Save order ID for further granting or tracking
    }

    is ApiResult.Failure -> {
        // Log debug information for troubleshooting
        Log.e("Checkout", "Failed to launch Checkout: ${result.error}")
        // TODO: Show user-friendly error message to player
    }
}
参数Type必填项描述
contextActivity是当前活动。
checkoutParamsCheckoutParams是Checkout 配置。

展示 Checkout

要为现有订单展示 Checkout UI，请使用 presentCheckout 或 presentWebCheckout 方法。 当你拥有通过服务器到服务器方式创建订单得到的订单 ID，或在恢复之前被放弃的 checkout 时使用此方法。

该启动模式使用对玩家体验具有完全控制权的 Native UI。

import com.aghanim.android.sdk.checkout.ui.api.presentCheckout
import com.aghanim.android.sdk.common.api.result.ApiResult
import android.util.Log

when (val result = aghanim.presentCheckout(
    context = context,
    orderId = orderId,
)) {
    is ApiResult.Success -> {
        // Checkout has launched successfully for the existing order
        val presentedOrderId = result.value
    }

    is ApiResult.Failure -> {
        // Log debug information for troubleshooting
        Log.e("Checkout", "Failed to present Checkout: ${result.error}")
        // TODO: Show user-friendly error message to player
    }
}
参数Type必填项描述
contextActivity是当前 Activity。
orderIdString是要打开的现有订单的 ID。

需要技术支持？
联系我们的集成技术团队： [email protected]

On this page