启用购买按钮和自定义结算

重要性说明

根据Apple最新的区域政策更新，开发者现在可以将用户从应用引导至外部网站完成虚拟物品的支付。

您可以在游戏中添加按钮、横幅、消息等多种引导方式，让用户一键跳转至安全的浏览器支付界面（网页商城或支付UI），全程合规，无违规风险。

通过Headless checkout集成购买按钮是创建自定义支付UI和独特用户体验的理想选择。该集成方案让用户能够从游戏无缝跳转到浏览器完成购买，支持包括通过Apple Pay一键支付在内的多种支付方式，提供快速、熟悉的移动端结算体验。

Headless checkout是基于无头应用架构的收款解决方案，功能通过API访问。该方法将后端和业务逻辑与UI分离。

如何为iOS游戏应用使用Headless checkout：

1. 创建自定义商店。
2. 将Headless checkout集成到商店中。
3. 在游戏中添加商店链接。

如果正在寻找最快的低代码集成方案，请查看基于网页商城的集成。

如果使用的是非艾克索拉建站器构建的自定义网页商城，并希望将现成的支付UI集成到游戏中，请查看通过艾克索拉Mobile SDK进行的集成。

运行机制

用户流程：

1. 用户在iOS设备上打开游戏应用。
2. 用户点击所需商品旁的购买按钮。
3. 商店在网页浏览器中打开。为确保流畅的用户体验，请实现端到端授权。
4. 用户在商店中选择商品并完成购买。
5. 交易成功后，用户将跳转回游戏应用。
6. 应用通过Webhook接收购买确认。

集成过程

1. 在发布商帐户中创建项目并与艾克索拉签署许可协议。
2. 创建商品目录。
3. 实现后端交互：创建令牌并设置Webhook。
4. 安装SDK。
5. 在应用程序侧集成SDK。
6. 在游戏中添加链接，引导用户前往已集成Headless checkout的商店。

创建项目并签署许可协议

发布商帐户是配置艾克索拉功能以及对分析和交易进行操作的主要工具。

要进行注册，请前往发布商帐户并创建帐户。要创建项目，请在侧边栏中单击创建项目并填写所需信息。您可以稍后修改这些设置。

要签署许可协议，请前往协议与税务信息 > 协议部分，填写协议表单。

创建商品目录

应用内购买(IAP)商品在艾克索拉生态系统中以虚拟物品的形式呈现，包含名称、描述、SKU和价格。要设置IAP SKU商品目录，您可以：

1. 上传JSON文件，快速将商品目录添加到发布商帐户。
2. 使用虚拟物品和货币 > 管理文档部分的API调用创建商品目录。

实现后端交互

创建令牌

配置Webhook

要启用Webhook：

1. 在发布商帐户中打开您的项目，前往项目设置 > Webhooks部分。
2. 在Webhook服务器字段中，指定服务器URL（即接收Webhook的地址），格式为https://example.com。您也可以使用Webhook测试工具中提供的URL。
3. 将默认生成一个给项目Webhook签名的密钥。如要生成新密钥，请单击刷新图标。
4. 单击启用Webhook。

要实现游戏内商店和支付管理的完整功能，必须实现对主要Webhook的处理：

安装SDK

1. 通过运行以下命令以npm包形式安装SDK：

1npm install --save @xsolla/pay-station-sdk

2. 通过传递环境参数初始化SDK：

1import { headlessCheckout } from '@xsolla/pay-station-sdk';
2
3await headlessCheckout.init({
4  sandbox: true,
5});

3. 为已初始化的SDK传递支付令牌：

1await headlessCheckout.setToken(accessToken);

在应用程序侧集成SDK

完成SDK的安装和初始化后：

1. 通过指定支付方式ID来初始化支付U。headlessCheckout.form.init方法会返回一个对象，用于后续与支付UI进行交互。

1await headlessCheckout.form.init({
2  paymentMethodId: 3175, // Apple Pay payment ID
3});

2. 添加show_fields事件处理以显示额外字段。

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'show_fields':
4      this.handleShowFieldsAction(nextAction);
5  }
6});

3. 在支付UI的HTML标记中添加以下组件：
   • 必需组件：
     • psdk-legal — 用于显示法律文件信息。
     • psdk-total — 用于显示总购买金额。
   • 支付表单组件。您可以使用内置的psdk-payment-form组件，也可以使用现成的组件手动创建支付UI元素。
   • 支付按钮组件 — psdk-apple-pay。您也可以使用psdk-submit-button组件，其中已包含psdk-apple-pay。

1<psdk-legal></psdk-legal>
2<psdk-total></psdk-total>
3
4
5<psdk-payment-form></psdk-payment-form>
6<psdk-apple-pay text="Apple Pay"></psdk-apple-pay>

4. 添加check_status事件处理以监听支付状态变化。

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'check_status': {
4      showStatus = true;
5    }
6  }
7});

5. 在支付UI的HTML标记中添加psdk-status组件以显示支付状态。

1@if (showStatus) {
2  <psdk-status></psdk-status>
3}

如何检测iOS商店区域

要确定当前iOS商店区域并根据区域调整SDK功能，请使用以下代码片段：

1[SKPaymentQueue loadCurrentStorefrontCountryCodeWithCompletion:^(NSString* _Nullable countryCode) {
2    settings.enablePayments = countryCode && [countryCode isEqualToString:@"USA"];
3
4    [[SKPaymentQueue defaultQueue] startWithSettings:settings];
5}];

1SKPaymentQueue.loadCurrentStorefrontCountryCode { countryCode in
2    settings.enablePayments = countryCode == "USA"
3
4    SKPaymentQueue.default().start(settings)
5}

loadCurrentStorefrontCountryCode方法会异步检索当前商店的三字母国家/地区代码。您可以使用此信息来启用或禁用特定区域的SDK功能。

您也可以直接使用Apple原生的Storefront，具体如下：

1let storefront = await Storefront.current   
2let countryCode = storefront?.countryCode
3
4settings.enablePayments = countryCode == "USA"
5
6SKPaymentQueue.default().start(settings)

通过Apple Pay一键支付

一键支付允许用户在支持的设备上使用Apple Pay，从而提供熟悉且安全的原生支付方式。要配置一键支付：

1. 创建请求以启用此选项。操作步骤：

   a. 在发布商帐户中前往支持中心部分。

   b. 单击提交请求。

   

   c. 在打开的窗口中，填写以下字段：

   • 摘要。例如，Apple Pay一键支付设置。
   • 描述。指定用于打开支付UI的域名，例如amazing.store.com。
   • 项目ID。从下拉列表中选择项目ID。如果要为多个项目配置一键支付选项，请在描述字段中指定它们的ID。

   d. 单击发送。

2. 等待您的域名关联文件。此步骤由艾克索拉进行：
   1. 艾克索拉向Apple注册您的域名。
   2. 艾克索拉从Apple处收到域名关联文件。
   3. 艾克索拉通过电子邮件将域名关联文件发送给您，并提供上传位置说明。

3. 如下所示更新SDK初始化脚本：

1const config: InitialOptions = {
2  isWebview: false,
3  theme: 'default',
4  language: parameters.language,
5  topLevelDomain: 'amazing.store.com',
6  isApplePayInstantFlowEnabled: true
7};
8
9await initHeadlessCheckoutLib(config);