跳到主要内容
版本：v3

礼包系统开发指南

提示

接入礼包系统之前，需完成应用配置。在 游戏服务 - 应用配置 中可获取 Client ID 和 Server Secret。请妥善保管这些信息，勿传给他人。

开始​

礼包系统接入适用于有请求接口能力的游戏，目前尚未提供完全离线的兑换码服务。

根据您的使用场景，您可以灵活对接以下不同兑换接口之一完成兑换流程。

方式接口名需游戏方校验后台设置的兑换条件需游戏方提供发送道具接口
游戏方校验/api/v1.0/cdk/game/submit-check✓✓
游戏方发送/api/v1.0/cdk/game/submit-send✗✓
无服务器兑换/api/v1.0/cdk/game/submit-simple✗✗
游戏方校验 Web/api/v1.0/cdk/page/submit-check✓✓
游戏方发送 Web/api/v1.0/cdk/page/submit-send✗✓

接入顺序​

  • 完成应用配置获取 Client ID 和 Server Secret 信息。
  • 进入 运营工具-礼包系统-服务器配置 选择性填写游戏方服务器信息并在其中配置发送通知接收地址用来发送相应道具。
  • 创建礼包活动导出兑换码，礼包配置完成准备测试。
  • 根据实际业务场景使用对应兑换接口完成兑换。

兑换流程​

兑换流程大致是：

  1. 根据接口文档提交 兑换码 与 配置信息等参数 给兑换接口。
  2. 兑换接口校验数据合法性。
  3. 兑换系统根据业务场景选择是否调用 游戏方提供的二次校验接口。（可选，当后台配置二次校验接口时会调用）
  4. 校验全部通过后根据不同接口判断是否调用 游戏方提供的发送道具接口 完成兑换。（可选，当后台配置发送道具接口时会调用）

有三种不同的兑换接口可以进行兑换，整体对接流程只要对接其一接口即可完成：

名称描述
游戏方校验如果您将使用服务器对接兑换系统，可以安全地保存密钥信息，并希望每次兑换时能通过您的应用程序来校验是否允许兑换，调用您的接口来发送道具，请使用此流程。
游戏方发送如果您将使用服务器对接兑换系统，可以安全地保存密钥信息，并希望调用您的应用程序接口来发送每次兑换的道具，请使用此流程。
无服务器兑换如果您希望不开发接口完成兑换流程，调用兑换接口后根据返回值来判断是否兑换失败，请使用此流程。

三种兑换场景​

游戏方校验​

当您请求兑换码 submit-check 接口进行兑换时，兑换系统会核对库存以及提交数据是否正确，兑换系统核对通过后会调用您在后台配置的二次校验接口并将后台设置的条件作为参数传给您来校验。 当您的接口校验通过后会继续将后台配置的奖品内容作为参数调用您的发送道具接口，当发送道具成功完成后本次兑换完成。 游戏方校验泳道图

游戏方发送​

当您请求兑换码 submit-send 接口进行兑换时，兑换系统会核对库存以及提交数据是否正确，核对完成后会继续将后台配置的奖品内容作为参数调用您的发送道具接口，当发送道具成功完成后本次兑换完成。 游戏方发送泳道图

无服务器兑换​

当您请求兑换码 submit-simple 接口进行兑换时，兑换系统会核对库存以及提交数据是否正确，兑换信息验证通过后本次兑换完成并将后台配置的道具信息返回给您。 无服务器兑换泳道图

对接兑换接口​

游戏方二次校验规范​

礼包活动在后台配置了自定义兑换条件后，使用带二次校验能力的接口进行兑换时，兑换系统会将此礼包活动的自定义兑换条件发送给游戏方进行二次校验，下图配置会对您在后台配置的接口发起如下请求：

自定义兑换条件

curl --location -g --request POST <后台配置的游戏方二次校验接口地址> \
--header 'Content-Type: application/json' \
--data-raw '{"activity_id":<后台活动ID>,"character_id":<用户ID>,"content":"[{\"condition\":\"level\",\"operate":\"gt\",\"value\":\"10\"}]","content_obj": [{"condition":"level","operate":"gt","value":"10"}],"ext":<兑换提交的ext参数>,"gift_code":<礼包码>,"nonce_str":"abcdc","server_code": <后台配置的code>,"sign":"42d2b58a8cd58b5e63d90524aaf63ef97e04f223","timestamp":1658825322,"custom":{<自定义维度>:[<自定义维度字段1>,<自定义维度字段2>]}}'

请在校验完成后返回带有特定字段的 JSON 返回值告诉兑换系统校验结果。

{
  "status": true,
  "errorCode": "字符串类型的错误code"
}

如果您希望返回字段命名风格保持一致也可以使用下划线命名风格返回信息。

{
  "status": true,
  "error_code": "字符串类型的错误code"
}

如果您并不要求兑换系统知晓兑换的错误信息可以直接返回 非 200 HTTP code 表示兑换失败，或者返回 HTTP code 200 表示兑换成功。 这样就无需按兑换系统的格式来返回信息。

请求参数类型含义
activity_id字符串礼包活动 ID
character_id字符串兑换的用户 ID
content字符串（嵌套 JSON 字符串）后台配置的自定义条件
content.condition字符串自定义条件-key
content.operate字符串关系-详情见其他
content.value字符串自定义条件-value
content_obj对象数组（和 content 含义相同）后台配置的自定义条件
content_obj.condition字符串自定义条件-key
content_obj.operate字符串关系-详情见其他
content_obj.value字符串自定义条件-value
ext字符串请求接口时传递的数值
gift_code字符串用户此次兑换的礼包码
nonce_str字符串此次请求的随机字符串
server_code字符串服务器 code
sign字符串签名
timestamp数字秒级时间戳
custom对象维度信息
custom.xxx字符数组自定义维度
返回参数类型含义
errorCode字符串错误类型，error_code 含义相同，优先取 errorCode
ext字符串（可选）需要透传给发送道具接口的字符串
status布尔值是否校验成功，true 为成功，false 为失败

游戏方发送道具规范​

后台设置的物品信息，在兑换系统完成兑换校验后会带上配置的参数请求 游戏方的发送道具接口。下图配置会对您在后台配置的接口发起如下请求： 自定义兑换条件

curl --location -g --request POST <后台配置的游戏方发送道具接口地址> \
--header 'Content-Type: application/json' \
--data-raw '{"activity_id": <后台活动ID>,"character_id":"uid","content":"[{\"name\": \"奖品名称\", \"number\": 2}]","content_obj": [{"name": "奖品名称", "number": 2}],"ext":<兑换提交的ext>,"gift_code":"gift_code","nonce_str":"abcdc","server_code":<后台配置的code>,"sign":"fbe23e6f6f5193355b29e9ea2913b1992af56346","check_ext":<二次兑换接口返回的ext>,"timestamp":1658827492,"custom":{<自定义维度>:[<自定义维度字段1>,<自定义维度字段2>]}}'

同样请在发送完成后返回带有特定字段的 JSON 返回值告诉兑换系统发送道具结果，也可以使用下划线命名返回字段。

{
  "status": true,
  "errorCode": "字符串类型的错误code"
}

如果您并不要求兑换系统知晓兑换的错误信息可以直接返回 非 200 HTTP code 表示兑换失败，或者返回 HTTP code 200 表示兑换成功。 这样就无需按兑换系统的格式来返回信息。

请求参数类型含义
activity_id字符串礼包活动 ID
character_id字符串兑换的用户 ID
server_code字符串服务器 code
content字符串（嵌套 JSON 字符串）后台配置的自定义奖品
content.name字符串奖品名称
content.number数字奖品数量
content_obj对象数组（和 content 含义相同）后台配置的自定义奖品
content_obj.name字符串奖品名称
content_obj.number整型奖品数量
ext字符串请求接口时传递的数值
gift_code字符串用户此次兑换的礼包码
nonce_str字符串此次请求的随机字符串
sign字符串签名
check_ext字符串二次校验透传过来的字符串参数
timestamp数字秒级时间戳
custom对象维度信息
custom.xxx字符数组自定义维度
返回参数类型含义
errorCode字符串错误类型，error_code 含义相同，优先取 errorCode
status布尔值是否校验成功，true 为成功，false 为失败

无服务器兑换​

使用无服务器兑换接口进行兑换时无需游戏方开发校验与发送接口。

但要注意在 后台配置礼包时需创建无服务器礼包。

兑换系统在接收到兑换请求后直接将兑换结果返回，游戏根据返回结果判断是否发放道具。

接口参数的详细说明请看文档下面的 三种兑换接口 - 无服务器兑换接口

维度配置​

在礼包后台中可以配置自定义维度信息，配置完成后创建活动礼包时可以勾选上相应维度信息。这些勾选上维度的礼包在二次校验，发送道具，以及无服务器返回结果里会带上勾选的维度参数，方便您对礼包做进一步分类业务的处理。

请求域名​

TapTap 版本域名
国内 taptap.cnhttps://poster-api.xd.cn
海外 taptap.iohttps://poster-api.xd.com

签名​

游戏方与兑换系统的接口通讯时将使用签名参数作为基础的安全验证，其中 Secret 为后台 游戏服务 - 应用配置 中 Server Secret。

提示

为了保证安全性，请勿将 Server Secret 信息放在客户端中使用以防敏感信息泄漏。

计算签名伪代码如下：

sign == sha1(timestamp + nonce_str + secret)

您也可以通过单元测试验证签名计算过程正确与否，如下是 golang 示例：

func TestMakeSign(t *testing.T) {
    timestamp := 1655724586
    nonceStr := "abcde"
    secret := "abc"
    sign := MakeSign(int64(timestamp), nonceStr, secret)
    assert.Equal(t, sign, "3cb8c38833fa742e7873378faddcbe5b56088482")
    //output: 3cb8c38833fa742e7873378faddcbe5b56088482
}

为了 Secret 不存放在客户端中，无服务器兑换返回的签名通过 Client ID 代替 Secret 进行验签。

sign == sha1(timestamp + nonce_str + client_id)
c_sign == sha1(timestamp + content + client_id)

二次校验兑换接口​

POST /api/v1.0/cdk/game/submit-check

Header Content-Type:application/json

请求参数：

请求参数类型是否必选含义
client_id字符串必传开发者后台 ClientId 信息
gift_code字符串必传这次兑换的兑换码
server_code字符串必传后台配置的服务器 code
character_id字符串必传游戏用户 ID
nonce_str字符串必传随机字符串，建议五位随机字符串
sign字符串必传签名
timestamp数字必传时间戳，单位为秒，有效期为一分钟
ext字符串非必传该字段会原封不动出现在 ext 中传给游戏二次校验接口
lang字符串非必传提示的语言类型，详情见其它

请求示例：

curl --location --request POST '<URL>/api/v1.0/cdk/game/submit-check' \
--header 'Content-Type: application/json' \
--data-raw '{"client_id":<后台ClientId>,"gift_code":<这次使用的兑换码>,"server_code":<服务器code>,"character_id":<游戏用户ID>,"nonce_str":<随机字符串>,"sign":<签名>,"timestamp":<时间戳>,"ext": <透传字段>}'

无二次校验兑换接口​

POST /api/v1.0/cdk/game/submit-send

Header Content-Type:application/json

请求参数：

请求参数类型是否必选含义
client_id字符串必传开发者后台 ClientId 信息
gift_code字符串必传这次兑换的兑换码
server_code字符串必传后台配置的服务器 code
character_id字符串必传游戏用户 ID
nonce_str字符串必传随机字符串，建议五位随机字符串
sign字符串必传签名
timestamp数字必传时间戳，单位为秒，有效期为一分钟
lang字符串非必传提示的语言类型，详情见其它

请求示例：

curl --location --request POST '<URL>/api/v1.0/cdk/game/submit-send' \
--header 'Content-Type: application/json' \
--data-raw '{"client_id":<后台ClientId>,"gift_code":<这次使用的兑换码>,"server_code":<服务器code>,"character_id":<游戏用户ID>,"nonce_str":<随机字符串>,"sign":<签名>,"timestamp":<时间戳>,"ext": <透传字段>}'

无服务器兑换接口​

POST /api/v1.0/cdk/game/submit-simple

Header Content-Type:application/json

请求参数：

请求参数类型是否必选含义
client_id字符串必传开发者后台 ClientId 信息
gift_code字符串必传这次兑换的兑换码
character_id字符串必传游戏用户 ID
nonce_str字符串必传随机字符串，建议五位随机字符串
sign字符串必传签名，该签名用 ClientId 代替 Secret
timestamp整型必传时间戳（秒）
lang字符串非必传提示的语言类型，详情见其它

返回参数：

返回参数类型含义
activity_id字符串礼包活动 ID
nonce_str字符串随机字符串
timestamp整型时间戳
content字符串（嵌套 JSON 字符串）后台配置的自定义奖品
content.name字符串奖品名称
content.number数字奖品数量
content_obj数组对象（含义与 content 相同）后台配置的自定义奖品
content_obj.name字符串奖品名称
content_obj.number整型奖品数量
sign字符串返回签名，验证返回数据没有被修改
c_sign字符串内容签名，验证返回数据没有被修改
error整形0 为成功，其他为失败码
success布尔是否成功
custom对象维度信息
custom.xxx字符数组自定义维度

请求示例：

curl --location --request POST '<URL>/api/v1.0/cdk/game/submit-simple' \
--header 'Content-Type: application/json' \
--data-raw '{"client_id":<后台ClientId>,"gift_code":<这次使用的兑换码>,"character_id":<游戏用户ID>,"nonce_str":<随机字符串>,"sign":<签名>,"timestamp":<时间戳>}'
Shell 请求示例：
#! /usr/bin/env bash

# TapDC 后台应用的 Client ID
client_id="请替换为控制台的 `Client ID`"
# 本次兑换的兑换码 在“礼包活动面板-数据-导出” 然后导出的文件里面可以看到格式如 S0LLC8ICB2MP2 的兑换码
gift_code="请替换为礼包面板中的兑换码"

# 随机字符串，建议五位随机字符串
nonce_str="A2B3Z"
# 游戏用户 ID
character_id="6347de128b****3ee825e029"
# 签名，该签名用 ClientId 代替 Secret
signed=$(echo -n $(date +%s)$nonce_str$client_id |openssl sha1)
RESULT_REQUEST=`curl --location --request POST 'https://poster-api.xd.cn/api/v1.0/cdk/game/submit-simple' \
--header 'Content-Type: application/json' \
--data-raw "{\"client_id\":\"$client_id\",\"gift_code\":\"$gift_code\",\"character_id\":\"$character_id\",\"nonce_str\":\"$nonce_str\",\"sign\":\"$signed\",\"timestamp\":$(date +%s)}"`

echo $RESULT_REQUEST
Android 请求示例：

可以参考 Android Demo 中礼包系统功能

C# 请求示例：
using UnityEngine.Networking;
using System;
using System.Text;
using System.Security.Cryptography;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class APIClient : MonoBehaviour
{
    private const string apiUrl = "https://poster-api.xd.cn/api/v1.0/cdk/game/submit-simple";
    private const string contentType = "application/json";
    private const string clientId = "hskcocvse6x1cgkklm";
    private const string giftCode = "NZ4mp2cztRMXH";
    private const string characterId = "879a0cdd9nnb917055ee";
    private const string nonceStr = "RFG7U";

    public GUISkin demoSkin;


    void Start()
    {

    }


     private void OnGUI()
    {

        GUI.skin = demoSkin;
        float scale = 1.0f;

        
        float btnWidth= Screen.width / 5 * 2;
        float btnWidth2 = btnWidth + 80 * scale;

        float btnHeight = Screen.height / 25;
        float btnTop = 30 * scale;
        float btnGap = 20 * scale;

        GUI.skin.button.fontSize = Convert.ToInt32(13 * scale);

        var style = new GUIStyle(GUI.skin.button) { fontSize = 20 };
        var labelStyle = new GUIStyle(GUI.skin.label) { fontSize = 30 };

        if (GUI.Button(new Rect((Screen.width - btnGap) / 2 - btnWidth, btnTop, btnWidth /2, btnHeight), "返回", style))
        {
            UnityEngine.SceneManagement.SceneManager.LoadSceneAsync(0);

        }

        btnTop += btnHeight + 20 * scale;

        if (GUI.Button(new Rect((Screen.width - btnGap) / 2 - btnWidth, btnTop, btnWidth, btnHeight), "无服务器兑换", style))
        {
             StartCoroutine(StartRequest());
        }


    }

    private IEnumerator StartRequest()
    {
        // 获取当前时间戳（秒）
        int timestamp = (int)(System.DateTime.UtcNow.Subtract(new System.DateTime(1970, 1, 1))).TotalSeconds;

        // 拼接并加密 sign 参数
        string sign = GetSign(timestamp, nonceStr, clientId);

        // 构建请求参数
        string requestBody = "{\"client_id\":\"" + clientId + "\",\"gift_code\":\"" + giftCode + "\",\"character_id\":\"" + characterId + "\",\"nonce_str\":\"" + nonceStr + "\",\"timestamp\":" + timestamp + ",\"sign\":\"" + sign + "\"}";

        // 创建 UnityWebRequest 对象
        UnityWebRequest request = new UnityWebRequest(apiUrl, "POST");

        // 设置请求头
        request.SetRequestHeader("Content-Type", contentType);

        // 设置请求体
        byte[] bodyRaw = Encoding.UTF8.GetBytes(requestBody);
        request.uploadHandler = new UploadHandlerRaw(bodyRaw);
        request.downloadHandler = new DownloadHandlerBuffer();

        // 发送请求
        yield return request.SendWebRequest();

        // 处理响应
        if (request.result == UnityWebRequest.Result.Success)
        {
            Debug.Log("API request succeeded");
            Debug.Log(request.downloadHandler.text);
        }
        else
        {

            Debug.Log("API request failed: " + request.error);
            Debug.Log(request.downloadHandler.text);

        }
    }

    private string GetSign(int timestamp, string nonceStr, string clientId)
    {
        // 拼接参数并进行 SHA1 加密
        string signString = timestamp.ToString() + nonceStr + clientId;
        byte[] signBytes = Encoding.UTF8.GetBytes(signString);
        byte[] signHash = new SHA1CryptoServiceProvider().ComputeHash(signBytes);
        string sign = BitConverter.ToString(signHash).Replace("-", "").ToLowerInvariant();

        return sign;
    }
}


返回示例：

{
    "activity_id":"TDS20220928151122U9H",
    "content":"[{\"name\": \"奖品\", \"number\": 2}]",
    "content_obj":[
        {
            "name":"奖品名称",
            "number":2
        }
    ],
    "nonce_str":"0DD4B",
    "sign":"5895f87d3dfb5e0918c1b195c015d9284609d122",
    "timestamp":1664354023,
    "success":true,
    "error":0,
    "c_sign":"12c6fc06c99a462375eeb3f43dfd832b08ca9e17",
    "custom":{
        "seasons":[
            "101",
            "102"
        ]
    }
}

返回格式​

成功返回

{
  "success": true,
  "messages": "成功",
  "error": 0
}

错误返回

返回参数含义
error错误码
message错误大致信息
info详细信息
info.dev_message开发提示
info.hint详细提示
{
  "error": 100001,
  "message": "输入有误",
  "info": {
    "dev_message": "",
    "hint": "test error"
  }
}

Web 嵌入兑换接口​

兑换系统提供了一套支持简易图形验证码的兑换接口，用来支持类似 Web 活动页的接入，与上述兑换接口流程相同但区别在于部分请求参数的改变。

获取验证码​

提示

验证码有效期为五分钟，失效后请重新获取新的验证码。

GET /api/v1.0/cdk/page/captcha-img

Header Content-Type:application/json

返回参数含义
imgbase64 格式的图片信息
key验证码 key，提交兑换时会需要带上

返回示例：

{
  "img": "data:image/png;base64,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",
  "key": "XfNTN1gQyvA2AcNOu1UN"
}

二次校验网页版​

POST /api/v1.0/cdk/page/submit-check

Header Content-Type:application/json

请求参数：

请求参数类型是否必选含义
client_id字符串必传开发者后台 ClientId 信息
gift_code字符串必传这次兑换的兑换码
server_code字符串必传后台配置的服务器 code
character_id字符串必传游戏用户 ID
nonce_str字符串必传随机字符串，建议五位随机字符串
verify_captcha_key字符串必传验证码 KEY
verify_captcha_code字符串必传用户提交的验证码答案
ext字符串非必传该字段会原封不动出现在 ext 中传给游戏二次校验接口
lang字符串非必传提示的语言类型，详情见其它

无二次校验网页版​

POST /api/v1.0/cdk/page/submit-send

Header Content-Type:application/json

请求参数：

请求参数类型是否必选含义
client_id字符串必传开发者后台 ClientId 信息
gift_code字符串必传这次兑换的兑换码
server_code字符串必传后台配置的服务器 code
character_id字符串必传游戏用户 ID
nonce_str字符串必传随机字符串，建议五位随机字符串
verify_captcha_key字符串必传验证码 KEY
verify_captcha_code字符串必传用户提交的验证码答案
lang字符串非必传提示的语言类型，详情见其它

其他​

错误码​

自定义状态码含义复现场景
100001输入有误发起请求的参数错误或者缺失部分必要参数
100004验证码输入错误，请重试校验图形验证码错误
100005参数错误提交的 ClientId 或者 ServerCode 错误
100006礼包码次数已达上限通兑码可领取次数达到上限（正常情况）
100025礼包码已经兑换过了唯一码已经被兑换过了
100008礼包码已经过期了礼包活动已过期
100009礼包活动暂未开放礼包活动暂停兑换，还没到活动开始时间
100010超出服务使用范围提交的 ServerCode 错误，不在礼包设置的范围
100011点击过快，请稍候再试唯一码连续提交
100012礼包码次数已达上限，请稍候再试通兑码库存不足（并发兑换时可能触发）
100013校验 cdkey 未通过二次校验游戏方返回了不通过结果
100014操作的人太多了，服务器正在拼命处理中兑换系统已达流量极限
100015发送道具失败发送道具游戏方返回了失败结果
100016该礼包码无效异常兑换码的提交
100017礼包码次数已达上限相同用户使用礼包中超过礼包设置的兑换数量
100018该活动无法使用此兑换接口礼包无服务器设置错误
100022该国家地区不支持此兑换码非此 ClientId 的唯一兑换码
500001服务器故障礼包系统出现通用性错误
500002外部接口校验错误与游戏方接口通讯发生了异常

多语言 Lang 参数​

Lang语言
ar_AR阿拉伯语
de_DE德语
zh_TW中文（繁體）
zh_CN中文（简体）
en_US英语
es_ES西班牙语
fr_FR法语
id_ID印度尼西亚语
it_IT意大利语
ja_JP日语
ko_KR韩语
pt_PT葡萄牙语
ru_RU俄语
tr_TR土耳其语
vi_VN越南语

自定义条件关系表​

关系 code含义
lt小于
le小于等于
eq等于
ne不等于
ge大于等于
gt大于

兑换系统出口 IP​

如果您配置的接口对请求 IP 有安全限制，请根据需要允许兑换系统的 IP 访问。

TapTap 版本IP
国内 taptap.cn59.110.228.98
海外 taptap.io8.214.95.148