Android

此章节为您提供 Android 端浮层式绑卡体验 SDK 的集成指南，帮助您快速开始手机 App 内绑卡相关页面的渲染。

集成准备

在您开始集成前，确保已完成以下环境准备工作：

已安装最新版本的 Android Studio。
目标运行环境须为 API 级别 19 及更高版本。
使用 Gradle 4.1 及以上版本。
配置物理机或模拟器，用于运行您的应用。

关键集成步骤

请根据以下步骤完成集成：

集成 SDK 资源包。

商户客户端

请查阅 Android 端集成 SDK 资源包文档。

通过 AMSVaulting 构造函数创建 SDK 实例：

商户客户端

创建 SDK 实例的过程包含以下步骤：

创建 configuration 对象：必传，Object 类型。包含所有配置参数：
- setLocale: 选传，String 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下几种语言，如果传入的值不是以下几种，将提供英语页面：
  - "en", "US"：英语
  - "pt", "BR"：葡萄牙语
  - "ko", "KR"：韩语
  - "es", "ES"：西班牙语
  - "fr", "FR"：法语
  - "nl", "NL"：荷兰语
  - "it", "IT"：意大利语
  - "de", "DE"：德语
  - "zh", "CN"：简体中文
  - "zh", "HK"：繁体中文
- setOption: 选传，用于设置是否使用沙箱环境，支持的值包括：
  - "sandbox", "true"：沙箱环境
  - "sandbox", "false"：生产环境
  - "notRedirectAfterComplete", "true"：默认值为 false，表示绑卡完成后跳回您的页面，当值为为空时同理。值为 true 表示绑卡完成后不跳转，您需要通过客户事件码自行控制绑卡完成后续流程。需要注意的是客户端返回的绑卡结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 资产绑定结果通知 或 资产绑定查询 接口返回结果为准。
创建 OnCheckoutListener 接口的实例，用于后续流程中对应事件发生时的处理，包含以下方法：
- OnEventCallback: 必传。收银台绑卡事件回调函数，返回事件码（eventCode）和事件信息（eventResult）。
将 OnCheckoutListener 接口的实例设置到 configuration 实例中，用于执行事件回调。
实例化 AMSVaulting。

创建 SDK 实例：

Java

Editor

发起 资产绑定会话创建 请求

商户服务端

商户客户端自行监听 添加卡 按钮的点击事件。当买家选择支付方式并点击绑卡按钮后，商户服务端向 Alipay 服务器发起 资产绑定会话创建 请求。一旦接收到 资产绑定会话创建 请求的响应，将响应中的 vaultingSessionData 值用于步骤四。

如果您需要在卡资产绑定完成后自动重定向买家到您的页面，通过 资产绑定会话创建 接口中的 redirectUrl 字段传入跳转地址。如果您希望通过客户端事件码自行控制绑卡完成后续流程，则无需传入该字段，并通过 onEventCallback 监听绑卡结果事件码。

注意：客户端返回的绑卡结果事件码仅用于客户端页面的跳转操作参考，绑卡状态的更新请以服务端 资产绑定结果通知 接口为准。

绑定资产会话创建请求示例

Editor

使用实例对象中的 createComponent 创建绑卡要素收集组件。

商户客户端

调用 createComponent() 并传入以下参数:
- activity: 必传。Activity 类型的一个对象，用于包含当前页面的上下文参数信息。
- sessionData：必传。String 类型。将 资产绑定会话创建 请求的响应中获取的 vaultingSessionData 字段的完整数据传入 sessionData 参数。
调用实例对象中的 onDestroy() 函数进行 SDK 组件的资源回收，请在以下两种场景中调用：
- 用户退出绑卡页面时，需要回收 资产绑定会话创建 中的组件资源。
- 用户发起多次绑卡时，需要回收上一次 资产绑定会话创建 中的组件资源。

创建配置对象：

Java

Editor

参考信息

事件码

SDK 提供的错误码如下：

SDK_INTERNAL_ERROR：SDK 内部错误。请联系 Antom 技术支持。
SDK_CREATEPAYMENT_PARAMETER_ERROR：createComponent 函数传入参数异常，请检查参数是否正确后更换 vaultingRequestId 重试请求。
SDK_INIT_PARAMETER_ERROR：AMSVaulting 函数传入参数异常。请检查参数是否正确后更换 vaultingRequestId 重试请求。
SDK_CREATECOMPONENT_ERROR：组件初始化异常。请联系 Antom 技术支持。
SDK_ABNORMAL_RENDERING_DATA：渲染数据异常。请重试初始化流程或联系技术支持排查。
SDK_SUBMIT_NETWORK_ERROR：网络原因，导致接口调用失败。在 submit 函数提交中可能会出现。请买家再尝试重新提交。

SDK 提供的状态码如下：

SDK_CALL_URL_ERROR：跳转商户页面失败。检查跳转商户链接是否可以正常可访问。若回跳 URL 可正常访问，请联系 Antom 技术支持。
SDK_CALL_URL_SUCCESS：跳转商户页面成功。无需后续操作。
SDK_FORM_VERIFICATION_FAILED：提交表单后校验不通过。SDK 会在要素收集页面展示表单错误。商户也可以通过文案引导用户输入正确信息。
SDK_DUPLICATE_SUBMISSION_BEHAVIOR：表单重复提交。商户可以通过文案提示用户，无需重复点击提交。

SDK 提供的绑卡结果码如下：

SDK_ASSET_BINDING_FAIL：绑卡失败。建议您根据 vaultingResultCode 错误码提示信息，并重新引导用户绑卡。
SDK_ASSET_BINDING_SUCCESSFUL：绑卡成功，需要注销SDK。建议重定向到绑卡结果页。
SDK_ASSET_BINDING_ERROR：绑卡异常。建议您等待绑卡结果通知或重新引导用户绑卡。

SDK 查询服务端绑卡状态（vaultingStatus）：

SUCCESS: 表示绑卡成功。
FAIL: 表示绑卡失败。

SDK 查询服务端结果码（result.resultCode）：

结果码	值	消息	建议
SUCCESS	S	Success	无需进一步操作。
PROCESS_FAIL	F	A general business failure occurred.	通常需要人工确认该问题。建议您联系 Antom 技术支持解决该问题。
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	无。

SDK 查询服务端绑卡结果码（vaultingResultcode）：

结果码	值	消息	建议
PROCESS_FAIL	F	A general business failure occurred.	通常需要人工确认该问题。建议您联系 Antom 技术支持解决该问题。

绑卡结果事件码处理示例：

Java

Editor

绑卡结果示例：

绑卡成功

绑卡失败

Editor

集成关键步骤代码示例

以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 资产绑定会话创建 接口的步骤示例，需要您自行处理服务端接口的调用。

Java

Editor