月卡接入指南

1. 域本概念

游戏中的月卡系统，支持月卡的配置与管理，可以让玩家在游戏中进行月卡激活、领取每日奖励等操作。
开发者可以将月卡系统和经济系统（使用方法参考「经济系统」）结合使用，使用经济系统中的资源作为月卡奖励，领取奖励时，资源将会被自动发放到玩家的背包内。

月卡系统在使用上主要分为 月卡配置、角色月卡 两个部分：

• 月卡配置：包括了月卡的名称、激活天数、奖励等配置信息，用户可以在UOS网站上进行月卡的配置与管理。
• 角色月卡：每个玩家角色在游戏中拥有的月卡实例，可以对其进行激活、领取每日奖励等操作。

月卡状态

状态	说明
Inactive（未激活）	角色尚未激活该月卡
Active（生效中）	月卡处于生效中，可以领取每日奖励
Expired（已过期）	月卡已超过有效期

奖励类型

• 购买奖励（Purchase Rewards）：玩家激活月卡时一次性获得的奖励
• 每日奖励（Daily Rewards）：玩家每天可领取的奖励

2. 功能配置与管理

进入UOS Passport 「月卡 -> 月卡管理」 页面进行月卡的配置与管理。

创建月卡

点击左上角 「创建月卡」 按钮进行月卡创建。

第一步：基本信息配置

配置说明：

• 唯一标识(SlugName)：月卡的唯一标识，同一个UOS APP下可以唯一定位一个月卡，仅支持字母、数字和-_的组合，且须以字母和数字作为开头，创建成功后不可更改
• 名称：月卡的显示名称
• 描述：月卡的描述信息
• 激活天数：单次激活后月卡的有效天数
• 最大累计天数：月卡可累计的最大天数，留空表示无限制。当玩家重复激活月卡时，剩余天数可以累加，但不会超过此限制

第二步：奖励配置

配置说明：

• 购买奖励：玩家激活月卡时一次性获得的奖励，点击「添加奖励」配置资源及数量
• 每日奖励：玩家每天可领取的奖励，点击「添加奖励」配置资源及数量
• 自定义属性：可选的自定义属性，以键值对形式存储，可用于扩展功能

创建成功后，在 「月卡管理」 页面中，可以查看已有月卡的基本情况，对月卡进行查看详情、编辑、删除等操作。

发布月卡

配置完成的月卡需要发布后才可以被正确使用。在 「月卡管理」 页面，通过发布状态开关可以执行月卡的发布与下架操作。

注意：为保证月卡数据的一致性，已发布的月卡只能修改其名称和描述，其它属性均无法被修改。

允许客户端激活月卡

默认情况下，月卡的激活需要通过服务端API进行。如果需要允许客户端SDK直接激活月卡，可以在月卡管理页面底部开启此配置。

注意：这是一个危险的操作，我们认为玩家月卡的激活应该由游戏服务器进行操作。建议您在充分理解后果并确信需要时才开启此配置。

角色月卡查询

进入UOS Passport 「月卡 -> 角色月卡查询」 页面，可以查询已存在的角色月卡概况。

月卡记录查询

进入UOS Passport 「月卡 -> 月卡记录查询」 页面，可以查询角色月卡的激活、续费记录。

3. 在 Unity 中接入 SDK

在接入 SDK 前请确保完成 「功能配置」
在接入 SDK 前，请确保在代码中引入了 Passport 的命名空间：

using Unity.Passport.Runtime;
using MonthlyCard;

接入用户登录模块

外部账号系统登录

参考 「外部账号系统登录」 正确接入外部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;
    }

1. 获取角色月卡信息

// 获取指定角色月卡的详细信息
PersonaMonthlyCardResponse res = await PassportFeatureSDK.MonthlyCard.GetPersonaMonthlyCard(slugName);

// 将月卡的名称打印出来
Debug.Log(res.MonthlyCard.DisplayName);

// 将月卡状态打印出来
Debug.Log($"Status: {res.MonthlyCard.Status}");

// 将剩余天数打印出来
Debug.Log($"Remaining Days: {res.MonthlyCard.RemainingDays}");

public class PersonaMonthlyCardResponse
{
    // 角色月卡信息
    public PersonaMonthlyCard MonthlyCard;
}

public class PersonaMonthlyCard
{
    // 月卡实例ID
    public string Id;
    // 月卡的唯一标识Slug
    public string SlugName;
    // 月卡的名称
    public string DisplayName;
    // 月卡的描述
    public string Description;
    // 所属的UOS App ID
    public string UosAppId;
    // 角色ID
    public string PersonaId;
    // 月卡状态 (Inactive/Active/Expired)
    public MonthlyCardStatus Status;
    // 激活时间（UTC）
    public Timestamp ActiveTime;
    // 到期时间（UTC）
    public Timestamp ExpirationTime;
    // 累计领取次数
    public uint TotalClaimed;
    // 最后领取时间（UTC）
    public Timestamp LastClaimTime;
    // 今日是否已领取
    public bool TodayClaimed;
    // 剩余天数
    public uint RemainingDays;
    // 每日奖励列表
    public List<RewardResource> Rewards;
    // 单次激活天数
    public uint DurationDays;
    // 最大累计天数（空值表示无限制）
    public uint? MaxDays;
}

public class RewardResource
{
    // 奖励资源的唯一标识slug, 即经济系统内资源(resource)的slug
    public string Slug;
    // 奖励资源的数量
    public uint Quantity;
    // 奖励资源的详细信息
    public ResourceDetail Detail;
}

public class ResourceDetail
{
    // 资源名称
    public string DisplayName;
    // 资源类型(Item/VirtualCurrency/Currency)
    public Economy.ResourceType ResourceType;
    // 资源的自定义属性
    public Dictionary<string, string> CustomData;
}

2. 激活月卡

需在UOS Passport 「月卡 -> 月卡管理」 页面开启「允许客户端激活月卡」后才可访问此客户端SDK接口。

// 激活角色月卡，成功后返回月卡信息
// 如果角色已有该月卡且未过期，将会累加有效期（受maxDays限制）
ActivatePersonaMonthlyCardResponse res = await PassportFeatureSDK.MonthlyCard.ActivatePersonaMonthlyCard(slugName);

// 将激活后的月卡信息打印出来
Debug.Log($"Status: {res.MonthlyCard.Status}");
Debug.Log($"Expiration Time: {res.MonthlyCard.ExpirationTime}");
Debug.Log($"Remaining Days: {res.MonthlyCard.RemainingDays}");

// 购买奖励（激活时一次性获得）
foreach (var reward in res.MonthlyCard.PurchaseRewards)
{
    Debug.Log($"Purchase Reward: {reward.Slug} x {reward.Quantity}");
}

public class ActivatePersonaMonthlyCardResponse
{
    // 角色月卡信息
    public PersonaMonthlyCard MonthlyCard;
}

3. 领取每日奖励

// 领取每日奖励，成功后返回领取的资源列表
ClaimMonthlyCardRewardResponse res = await PassportFeatureSDK.MonthlyCard.ClaimMonthlyCardReward(slugName);

// 将领取的奖励资源打印出来
foreach (var resource in res.Resources)
{
    Debug.Log($"Claimed: {resource.Slug} x {resource.Quantity}");
}

public class ClaimMonthlyCardRewardResponse
{
    // 本次领取的奖励资源
    public List<RewardResource> Resources;
}

4. 使用场景示例

普通月卡

配置一个30天有效期的月卡，玩家激活后每天可领取奖励。

配置步骤：

1. 创建月卡，设置激活天数为30天
2. 配置每日奖励（如：金币 x 100、钻石 x 10）
3. 可选：配置购买奖励（如：钻石 x 300）
4. 发布月卡

玩家流程：

1. 玩家通过游戏内购买或其他方式获得月卡
2. 游戏服务端调用激活接口为玩家激活月卡
3. 玩家每天登录游戏后领取每日奖励

5. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class MonthlyCard
        {
            // 获取角色月卡信息
            // slugName: 月卡的唯一标识
            public static async Task<PersonaMonthlyCardResponse> GetPersonaMonthlyCard(string slugName){}

            // 激活角色月卡（需在app下开启「允许客户端激活月卡」配置）
            // slugName: 月卡的唯一标识
            public static async Task<ActivatePersonaMonthlyCardResponse> ActivatePersonaMonthlyCard(string slugName){}

            // 领取每日奖励
            // slugName: 月卡的唯一标识
            public static async Task<ClaimMonthlyCardRewardResponse> ClaimMonthlyMonthlyCardReward(string slugName){}
        }
    }
}

服务端 API

参见 「Passport 服务端API接入指南」 。

客户端 API

参见 「Passport 客户端API接入指南」 。

错误码

参见 「Passport 错误码」 。