邮件接入指南

1. 基本概念

游戏中的邮件系统，可以让玩家阅读、删除邮件，领取邮件附件中的资源。运营人员可以通过后台管理系统群发系统更新、活动通知、奖励或补偿邮件。每个玩家的邮箱容量上限为1000封邮件。邮箱只保留最近12个月的历史数据，超出的将会定期清除。
开发者可以将邮件系统和经济系统（使用方法参考「经济系统SDK」）结合使用， 使用经济系统中的资源作为邮件附件，领取邮件时，资源将会被发放到玩家的背包内。
邮件系统主要分为 邮件模板、发送记录、邮件 三个部分：

• 邮件模板：用户需通过邮件模板设定邮件的内容、进行邮件的发送，配置信息包含了发送范围、发送时间、过期时间、邮件标题、正文、附件等内容。
• 发送记录：用户每次使用邮件模板发送邮件时，将会产生一条发送记录。通过发送记录，可以对同一批次的邮件进行搜索、查看、撤回等操作。
• 邮件：玩家收件箱中的邮件本身，邮件分为未读（Unread）、未领取（Unconsumed）、已完成（Completed）三个状态，玩家可以对邮件进行阅读、领取操作。

2. 功能配置与管理

进入UOS Passport 「邮件 -> 模板管理」 页面进行邮件模板的配置与管理。

创建模板

点击左上角 「创建邮件模板」 按钮进行礼包创建。
用户可以选择新建一个空白的模板，或者导入已有的模板，以此为基础进行创建。

配置说明

• 唯一标识(SlugName)：邮件模板的唯一标识， 可以唯一定位一个邮件模板，仅支持字母、数字和-_的组合，且须以字母和数字作为开头，设置后不可更改
• 名称：模板的显示名称
• 过期时间
  • 过期时间是指使用该模板的邮件发送后的过期时间，有指定时长和指定时刻两种选择
  • 指定时长：邮件从玩家收到开始，经过指定时长后过期
  • 指定时刻：邮件到达某一指定的时刻后过期
• 发送范围：发送邮件时发送的对象范围，可选所有人、服务器、角色三种发送范围

• 标题：邮件的标题
• 副标题：邮件的副标题，可以为空
• 来源：邮件的来源
• 正文内容：邮件的正文内容

• 附件
  • 资源：经济系统中的资源，需要在经济系统中进行配置后，再进行选取
  • 数量：资源的数量

至此，我们创建了一个新的邮件模板，在 「模板管理」 页面中，我们可以对模板进行查看详情、发送邮件、编辑模板的操作。

模板详情

在 「模板详情」 页面，用户可以查看模板的配置信息、邮件内容、发送记录、邮件列表等信息，也可以对邮件模板进行发送、编辑、删除的操作。

编辑模板

用户可以在 「模板管理」 或 「模板详情」 页面编辑邮件模板。 对于已经有发送记录的邮件模板，只能对模板的名称和邮件文本内容进行修改。 模板邮件内容的改动，会使已发送的邮件也发生相应的改动，请谨慎操作。

发送邮件

用户可以在 「模板管理」 或 「模板详情」 页面进行发送邮件操作，发送时可以配置发送的时间、对象和附件内容。

发送范围	发送模式	发送时间	发送对象	附件内容
所有人	需调用「接收邮件」方法接收	支持配置	所有人	沿用模板附件
服务器	需调用「接收邮件」方法接收	支持配置	服务器ID	沿用模板附件
角色	直接发送	即刻发送	角色ID	可覆盖模板附件

配置说明

• 接收开始时间：邮件可被玩家接收的开始时间，默认为当前时间。发送范围为所有人或服务器时生效。
• 接收截止时间：邮件可被玩家接收的截止时间，默认为永久有效。发送范围为所有人或服务器时生效。
• 在接受开始时间到截止时间期间，玩家都可以上线调用 「接收邮件」 方法接收邮件。
• 例如：发送特定时间段的"节日庆典邮件"（如10月1日0点到10月8日0点），玩家需在这段时间内上线进行邮件的接收。

• 发送对象：此次发送的对象，根据发送范围填入对应的角色ID或服务器ID
• 附件：默认为发送模板的附件内容，发送范围为角色时可以进行修改覆盖

撤回邮件

用户可以在 「发送记录」 中对某次发送进行撤回操作。如果发送范围是所有人或服务器，撤回会将此次发送的所有邮件都撤回，因此请谨慎使用此功能。

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;
    }

1. 接收邮件

// 对发送范围为所有人或服务器的邮件，需要进行接收后才会出现在角色的收件箱内。
// 通常建议在游戏初始化、场景切换等时机进行接收邮件
await PassportFeatureSDK.Inbox.ReceiveMessages();

2. 查看收件箱

Inbox.ViewInboxResponse inboxRes = await PassportFeatureSDK.Inbox.ViewInbox(0, 20);

// 将收件箱内的邮件总数打印出来
Debug.Log(inboxRes.Total);

// 将收件箱内的邮件标题打印出来
foreach (var message in inboxRes.Messages)
{
    Debug.Log(message.Title);
}

public class ViewInboxResponse
{
    // 收件箱内的邮件总数
    public uint Total;
    // 本次搜索的起始位置
    public uint Start;
    // 本次搜索的目标数量
    public uint Count;
    // 符合条件的邮件列表
    public List<InboxMessage> Messages;
}

public class InboxMessage
{
    // 邮件ID
    public string Id;
    // 所属的UOS App ID
    public string UosAppId;
    // 邮件模板的唯一标识Slug
    public string TemplateSlug;
    // 发送记录ID
    public string RecordId;
    // 角色ID
    public string PersonaId;
    // 邮件状态，Unread/Unconsumed/Completed
    public string Status;
    // 邮件标题
    public string Title;
    // 邮件副标题
    public string Subtitle;
    // 邮件正文内容
    public string Body;
    // 邮件附件内容
    public List<AttachmentItem> Attachment;
    // 邮件来源
    public string Source;
    // 邮件发送时间（UTC）
    public Timestamp SendAt;
    // 邮件过期时间（UTC）
    public Timestamp ExpiredAt;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
}

public class AttachmentItem
{
    // 附件资源的唯一标识slug, 即经济系统内资源(resource)的slug
    public string ItemSlug;
    // 附件资源的数量
    public uint Quantity;
    // 附件资源的详细信息
    public ResourceInfo Resource;
}

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

3. 操作单个邮件

// InboxMessage message

// 阅读邮件
Inbox.ReadMessageResponse readRes = await PassportFeatureSDK.Inbox.ReadMessage(message.Id);

// 将阅读后邮件的状态打印出来
Debug.Log(readRes.Message.Status);

// 领取邮件
Inbox.ConsumeMessageResponse consumeRes = await PassportFeatureSDK.Inbox.ConsumeMessage(message.Id);

// 将领取后邮件的状态打印出来
Debug.Log(consumeRes.Message.Status);

// 删除邮件
await PassportFeatureSDK.Inbox.DeleteMessage(message.Id);

public class ReadMessageResponse
{
    // 阅读后的邮件基本信息
    public InboxReadMessage Message;
}

public class InboxReadMessage
{
    // 邮件ID
    public string Id;
    // 邮件状态
    public string Status;
}

public class ConsumeMessageResponse
{
    // 领取后的邮件基本信息
    public InboxConsumedMessage Message;
}

public class InboxConsumedMessage
{
    // 邮件ID
    public string Id;
    // 邮件状态
    public string Status;
    // 邮件附件内容
    public List<AttachmentItem> Attachment;
}

4. 批量操作邮件

// 阅读全部邮件，将所有Unread的邮件状态变为Completed（无附件）、Unconsumed（有附件）
Inbox.ReadMessagesResponse readAllRes = await PassportFeatureSDK.Inbox.ReadAllMessages();

// 将阅读后所有邮件的状态打印出来
foreach (var message in readAllRes.Messages)
{
    Debug.Log(message.Status);
}

// 领取全部带有附件的邮件，将邮件状态变为Completed
Inbox.ConsumeMessagesResponse consumeAllRes = await PassportFeatureSDK.Inbox.ConsumeAllMessages();

// 将领取后所有邮件的状态打印出来
foreach (var message in consumeAllRes.Messages)
{
    Debug.Log(message.Status);
}

// 删除所有已完成的邮件
Inbox.DeleteMessagesResponse deleteAllRes = await PassportFeatureSDK.Inbox.DeleteAllMessages();

// 将删除邮件的数量打印出来
Debug.Log(deleteAllRes.Count);

public class ReadMessagesResponse
{
    // 阅读后的邮件基本信息列表
    public List<InboxReadMessage> Messages;
}

public class ConsumeMessagesResponse
{
    // 领取后的邮件基本信息列表
    public List<InboxConsumedMessage> Messages;
}

public class DeleteMessagesResponse
{
    // 删除的邮件数量
    public uint Count;
}

4. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class Inbox
        {
            // 接收邮件
            public static async Task<Empty> ReceiveMessages(){}

            // 查看收件箱
            // start: 搜索的起始位置，默认为0
            // count: 搜索的目标数量，默认为20，最大为50
            public static async Task<ViewInboxResponse> ViewInbox(uint start = 0, uint count = 20){}

            // 阅读邮件
            // messageId: 邮件ID
            public static async Task<ReadMessageResponse> ReadMessage(string messageId){}

            // 领取邮件
            // messageId: 邮件ID
            public static async Task<ConsumeMessageResponse> ConsumeMessage(string messageId){}

            // 删除邮件
            // messageId: 邮件ID
            public static async Task<Empty> DeleteMessage(string messageId){}

            // 阅读全部邮件
            public static async Task<ReadMessagesResponse> ReadAllMessages(){}

            // 领取全部带有附件的邮件
            public static async Task<ConsumeMessagesResponse> ConsumeAllMessages(){}

            // 删除所有已完成的邮件
            public static async Task<DeleteMessagesResponse> DeleteAllMessages(){}
        }
    }
}

服务端 API

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

客户端 API

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

错误码

参见 「Passport 错误码」 。