1. 基本概念

游戏中的礼包系统，支持礼包活动的配置与管理，玩家在游戏中可以兑换礼包码来获取相应的奖励。
礼包系统需结合「经济系统」使用，用于配置礼包内的资源奖励。

2. 功能配置与管理

进入UOS Passport 「礼包 -> 活动管理」 页面进行礼包的配置与管理
在该页面用户可以看到礼包活动的简要信息，包括状态、类型、领取量等

配置礼包

点击左上角 「创建礼包活动」 按钮进行礼包创建。

名称
- 礼包活动的名称，不能为空，可以根据开发者需求设置
开始时间
- 默认为即刻开始。到达该时间后，礼包活动生效，可以进行兑换
结束时间
- 默认为永久有效。该时间过后，礼包活动失效，无法兑换
限定兑换使用范围（Scope）
- 礼包兑换的限定范围，默认为无限定。Scope可以是平台信息、玩家属性等
- 在玩家兑换时可以附上Scope信息，只有属于限定Scope范围才能成功兑换

礼包内容
- 礼包所包含的游戏资源，不能为空
- 资源：经济系统中的资源，需要在「经济系统」中进行配置后，再进行选取
- 数量：资源的数量
发放方式
- 使用礼包码兑换礼包后，礼包奖励的发放方式
- 直接发放：奖励将直接发放至玩家背包内
- 通过邮件发放：将会给玩家发送包含礼包奖励的邮件，玩家通过邮件领取奖励。需要在「邮件系统」中先配置发送范围为“角色”的邮件模板

礼包码
- 通兑码
  - 一个礼包活动只能有一个通兑码，所有玩家都可以使用该码兑换
  - 支持手动输入和自动生成两种方式
- 唯一码
  - 每个码都是随机的、唯一的，且只能使用一次
  - 前缀：定制唯一码的固定前缀，需满足（礼包码长度 - 前缀长度 ≥ 8）
  - 限定兑换次数：每个游戏角色在该礼包活动中能够使用的唯一码数量，默认为1
- 礼包码长度范围8-20，支持英文和数字，不区分大小写

发布礼包

礼包活动在发布后才会正常生效，礼包码才能够被兑换
「活动管理」 和 「礼包详情」 页面都可以对礼包活动进行发布或下架

获取礼包码

通用码
- 在 「礼包详情」 页面中可以查看通用码的具体值

唯一码
- 可以在 「活动管理」 和 「礼包详情」 页面进行礼包码的生成操作
- 生成礼包码时，可以设定批次（便于统一管理）和数量、绑定自定义属性，生成后，可以将礼包码导出至本地
- 绑定自定义属性
  - 开启后可以对生成的礼包码绑定自定义属性，在文本框中贴入需要绑定的属性。
  - 第一行表示属性的key值，之后每一行表示一个礼包码属性的value值，多个值之间用英文逗号隔开
  - 每一行的value值数量应与key值的数量保持一致，总行数=礼包码数量+1
  - 示例
```
生成2个礼包码，每个礼包码绑定2条自定义属性，其key分别为key1,key2，贴入的文本应为：
key1,key2
value01,value02
value11,value12
生成后，2个礼包码的自定义属性分别为
{"key1": "value01", "key2": "value02"}
{"key1": "value11", "key2": "value12"}
```

作废礼包码

作废操作仅对唯一码支持，对于部分不需要的礼包码，可以在 「礼包详情」 页面进行批量作废操作

也可以在 「礼包码查询」 页面作废单个唯一码

3. 在 Unity 中接入 SDK

在接入 SDK 前请确保完成 「功能配置」，创建了相应的礼包活动，活动处于运行中的状态。
在接入 SDK 前，请确保在代码中引入了 Passport 的命名空间：

using Unity.Passport.Runtime;

外部账号系统登录

参考「外部账号系统登录」正确接入外部ID系统。确保在调用礼包相关方法之前 已完成外部ID系统的接入

Passport登录

参考「Passport 登录」正确接入 Passport Login，确保在调用礼包相关方法之前 用户已经登录完成。
安装并初始化 Feature SDK
- 在 UOS Launcher 服务列表中，找到 Passport Feature，点击 「Install SDK」，将服务 SDK 安装到当前项目中
- 初始化 Feature SDK
```
try
{
await PassportFeatureSDK.Initialize();
}
catch (PassportException e)
{
Debug.Log($"failed to initialize sdk: {e.Message}");
throw;
}
```

核销礼包码

示例：礼包码为VIP66666，玩家的scope信息为手机操作系统信息ios

var redeemedToken = await PassportFeatureSDK.Token.RedeemToken("VIP66666", "ios");

// 获取礼包内的奖励资源信息
var gifts = redeemedToken.TokenInstance.Gifts;

4. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class Token
        {
            // 核销礼包码
            // code: 礼包码的值
            // scope: 核销时的限定条件，满足礼包活动的限定范围条件时，可以正常兑换，默认为空
            public static async Task<TokenInstanceResponse> RedeemToken(string code, string scope = ""){}
        }
    }
}