跳到主要内容
版本：v4

API 参考

注意事项​

初始化要求

调用好友模块任何 API 函数前，必须先成功调用 TapSDK_Init 进行初始化。未初始化或初始化失败时，调用好友模块函数将返回错误或者非预期结果。

字符串编码

好友模块所有 API 函数接受和返回的字符串参数（char*），都是 UTF-8 编码，请根据项目实际情况自行转换。

用户授权

数据类型定义​

枚举类型​

TapRelation_SyncRelationshipActionType​

同步好友关系的动作类型：

enum {
    TapRelation_SyncRelationshipActionType_Add = 0,    // 新增好友关系
    TapRelation_SyncRelationshipActionType_Remove = 1, // 移除好友关系
};
typedef uint32_t TapRelation_SyncRelationshipActionType;

结构体类型​

字节对齐

好友模块使用的所有结构体类型，均使用 8 字节对齐：#pragma pack(push, 8)。

TapRelationFollowStatus​

关注关系：

typedef struct {
    bool following;  // 是否关注了对方
    bool followed;   // 是否被对方关注（粉丝）
    bool blocking;   // 是否拉黑了对方
    bool blocked;    // 是否被对方拉黑
} TapRelationFollowStatus;

TapRelationFriendInfo​

好友信息：

typedef struct {
    const char* open_id;  // 好友 OpenID
    const char* name;     // 用户名
    const char* alias;    // 备注名
    const char* avatar;   // 头像 URL
    TapRelationFollowStatus follow_status;
    int64_t created_at;   // 关系创建时间戳，1970 年开始的秒数
} TapRelationFriendInfo;

TapRelationGetFriendListRequest​

拉取好友列表（互关）请求，用于 TapRelation_AsyncGetFriendList()：

typedef struct {
    const char* continuation_token; // 用于拉取下一页。拉第一页时传 NULL
} TapRelationGetFriendListRequest;

TapRelationGetFriendListResponse​

TapRelation_AsyncGetFriendList() 的回调数据，通过 TapEventID::RelationGetFriendList 返回：

typedef struct {
    int64_t                       request_id;          // 请求 ID。原样返回开发者调用异步接口时传入的 ID
    const TapSDK_Error*           error;               // 错误信息。NULL 表示成功；非 NULL 表示请求失败
    uint32_t                      friend_count;        // friends 数组长度
    const TapRelationFriendInfo*  friends;             // 互关好友列表
    const char*                   continuation_token;  // 下一页 token，没有下一页时为 NULL
} TapRelationGetFriendListResponse;

TapRelationGetFollowingListRequest​

拉取关注列表（我关注的）请求，结构与 TapRelationGetFriendListRequest 一致：

typedef TapRelationGetFriendListRequest TapRelationGetFollowingListRequest;

TapRelationGetFollowingListResponse​

TapRelation_AsyncGetFollowingList() 的回调数据，通过 TapEventID::RelationGetFollowingList 返回：

typedef struct {
    int64_t                       request_id;
    const TapSDK_Error*           error;
    uint32_t                      following_count;     // followings 数组长度
    const TapRelationFriendInfo*  followings;          // 我关注的用户列表
    const char*                   continuation_token;  // 下一页 token，没有下一页时为 NULL
} TapRelationGetFollowingListResponse;

TapRelationGetFanListRequest​

拉取粉丝列表（关注我的）请求，结构与 TapRelationGetFriendListRequest 一致：

typedef TapRelationGetFriendListRequest TapRelationGetFanListRequest;

TapRelationGetFanListResponse​

TapRelation_AsyncGetFanList() 的回调数据，通过 TapEventID::RelationGetFanList 返回：

typedef struct {
    int64_t                       request_id;
    const TapSDK_Error*           error;
    uint32_t                      fan_count;           // fans 数组长度
    const TapRelationFriendInfo*  fans;                // 粉丝列表
    const char*                   continuation_token;  // 下一页 token，没有下一页时为 NULL
} TapRelationGetFanListResponse;

TapRelationShowUserProfileRequest​

展示用户名片请求，用于 TapRelation_ShowUserProfile()：

typedef struct {
    const char* open_id;  // 用户 OpenID
    const char* union_id; // 用户 UnionID。与 open_id 二选一，同时传递会报错
} TapRelationShowUserProfileRequest;

TapRelationSyncRelationshipWithOpenIDRequest​

按 OpenID 同步好友关系请求，用于 TapRelation_AsyncSyncRelationshipWithOpenID()：

typedef struct {
    TapRelation_SyncRelationshipActionType action;
    const char* nickname;        // 本人昵称，不允许 NULL，不允许空字符串
    const char* friend_nickname; // 对方昵称，不允许 NULL，不允许空字符串
    const char* friend_open_id;  // 对方 OpenID
} TapRelationSyncRelationshipWithOpenIDRequest;

TapRelationSyncRelationshipWithUnionIDRequest​

按 UnionID 同步好友关系请求，用于 TapRelation_AsyncSyncRelationshipWithUnionID()：

typedef struct {
    TapRelation_SyncRelationshipActionType action;
    const char* nickname;        // 本人昵称，不允许 NULL，不允许空字符串
    const char* friend_nickname; // 对方昵称，不允许 NULL，不允许空字符串
    const char* friend_union_id; // 对方 UnionID
} TapRelationSyncRelationshipWithUnionIDRequest;

TapRelationSyncRelationshipResponse​

同步好友关系的回调数据，通过 TapEventID::RelationSyncRelationshipWithOpenID 或 TapEventID::RelationSyncRelationshipWithUnionID 返回：

typedef struct {
    int64_t              request_id;
    const TapSDK_Error*  error; // NULL 表示成功；非 NULL 表示请求失败
} TapRelationSyncRelationshipResponse;

TapRelationInviteTeamRequest​

邀请好友加入队伍请求，用于 TapRelation_InviteTeam()：

typedef struct {
    const char* team_id; // 组队参数，必须为 ASCII，且不能包含空格、双引号、换行符等特殊符号
} TapRelationInviteTeamRequest;

TapRelationInviteReceivedNotification​

  • 被邀请方接受邀请后，如果游戏运行中，游戏内会收到该事件通知。
  • 接受进入游戏邀请（邀上线）对应 TapEventID::RelationGameInviteReceived，接受组队邀请对应 TapEventID::RelationTeamInviteReceived。
typedef struct {
    const char* open_id;  // 发起邀请的好友 OpenID
    const char* union_id; // 发起邀请的好友 UnionID
    const char* team_id;  // 仅组队邀请（RelationTeamInviteReceived）有效，进入游戏邀请时为 NULL
} TapRelationInviteReceivedNotification;

TapRelationUnreadMessageCountNotification​

未读消息数变化通知，通过 TapEventID::RelationUnreadMessageCountChanged 返回：

typedef struct {
    uint32_t count; // 最新未读消息数
} TapRelationUnreadMessageCountNotification;

TapRelationNewFanCountNotification​

新增粉丝数变化通知，通过 TapEventID::RelationNewFanCountChanged 返回，结构与 TapRelationUnreadMessageCountNotification 一致：

typedef TapRelationUnreadMessageCountNotification TapRelationNewFanCountNotification;

ITapRelation​

好友模块接口对象，通过 TapRelation() 获取：

typedef struct ITapRelation ITapRelation;

函数说明​

TapRelation​

获取好友模块单例对象。

ITapRelation* TapRelation();

返回值：

  • 好友模块单例对象

使用示例：

ITapRelation* relation = TapRelation();

TapRelation_AsyncGetFriendList​

发起拉取互关好友列表的异步请求。请求发起成功后，结果通过 TapEventID::RelationGetFriendList 事件返回。

TapSDK_Result TapRelation_AsyncGetFriendList(
    ITapRelation* self,
    int64_t request_id,
    const TapRelationGetFriendListRequest* request
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回，用于对应原始请求
  • request：拉取好友列表请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败，不会触发回调

使用示例：

TapRelationGetFriendListRequest req{};
req.continuation_token = nullptr; // 首页传 NULL，翻页时使用上次回调返回的 token

auto ret = TapRelation_AsyncGetFriendList(
    TapRelation(),
    ++gRequestID,
    &req);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败，不会触发回调
    return -1;
}

TapRelation_AsyncGetFollowingList​

发起拉取关注列表（我关注的用户）的异步请求。请求发起成功后，结果通过 TapEventID::RelationGetFollowingList 事件返回。

TapSDK_Result TapRelation_AsyncGetFollowingList(
    ITapRelation* self,
    int64_t request_id,
    const TapRelationGetFollowingListRequest* request
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：拉取关注列表请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败，不会触发回调

TapRelation_AsyncGetFanList​

发起拉取粉丝列表（关注我的用户）的异步请求。请求发起成功后，结果通过 TapEventID::RelationGetFanList 事件返回。

TapSDK_Result TapRelation_AsyncGetFanList(
    ITapRelation* self,
    int64_t request_id,
    const TapRelationGetFanListRequest* request
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：拉取粉丝列表请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败，不会触发回调

TapRelation_AsyncSyncRelationshipWithOpenID​

发起按 OpenID 同步好友关系的异步请求。请求发起成功后，结果通过 TapEventID::RelationSyncRelationshipWithOpenID 事件返回。

TapSDK_Result TapRelation_AsyncSyncRelationshipWithOpenID(
    ITapRelation* self,
    int64_t request_id,
    const TapRelationSyncRelationshipWithOpenIDRequest* request
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：同步好友关系请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败，不会触发回调

使用示例：

TapRelationSyncRelationshipWithOpenIDRequest req{};
req.action = TapRelation_SyncRelationshipActionType_Add;
req.nickname = "我的游戏昵称";
req.friend_nickname = "对方游戏昵称";
req.friend_open_id = "friend_open_id";

auto ret = TapRelation_AsyncSyncRelationshipWithOpenID(
    TapRelation(),
    ++gRequestID,
    &req);
if (ret != TapSDK_Result_OK) {
    return -1;
}

TapRelation_AsyncSyncRelationshipWithUnionID​

发起按 UnionID 同步好友关系的异步请求。请求发起成功后，结果通过 TapEventID::RelationSyncRelationshipWithUnionID 事件返回。

TapSDK_Result TapRelation_AsyncSyncRelationshipWithUnionID(
    ITapRelation* self,
    int64_t request_id,
    const TapRelationSyncRelationshipWithUnionIDRequest* request
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：同步好友关系请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败，不会触发回调

TapRelation_GetUnreadMessageCount​

同步获取当前未读消息数。

TapSDK_Result TapRelation_GetUnreadMessageCount(
    ITapRelation* self,
    uint32_t* count
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • count：出参。调用成功（返回 TapSDK_Result_OK）时写入当前未读消息总数；返回非 TapSDK_Result_OK 时不修改

返回值：

  • TapSDK_Result：TapSDK_Result_OK 表示成功

注意事项：

TapRelation_GetNewFanCount​

同步获取当前新增粉丝数。

TapSDK_Result TapRelation_GetNewFanCount(
    ITapRelation* self,
    uint32_t* count
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • count：出参。调用成功（返回 TapSDK_Result_OK）时写入当前新增粉丝数；返回非 TapSDK_Result_OK 时不修改

返回值：

  • TapSDK_Result：TapSDK_Result_OK 表示成功

注意事项：

TapRelation_ShowIM​

激活 TapTap 启动器好友聊天窗口，可以给好友发消息、管理好友等。

TapSDK_Result TapRelation_ShowIM(
    ITapRelation* self
);

参数：

  • self：TapRelation() 返回的好友模块单例对象

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败

TapRelation_ShowUserProfile​

激活 TapTap 启动器用户名片窗口，显示指定用户的基本信息。

TapSDK_Result TapRelation_ShowUserProfile(
    ITapRelation* self,
    const TapRelationShowUserProfileRequest* request
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • request：展示用户名片请求参数。open_id 与 union_id 二选一，同时传递会报错

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败

使用示例：

TapRelationShowUserProfileRequest req{};
req.open_id = "target_open_id";

auto ret = TapRelation_ShowUserProfile(TapRelation(), &req);
if (ret != TapSDK_Result_OK) {
    return -1;
}

TapRelation_InviteGame​

激活 TapTap 启动器好友邀请窗口，邀请好友进入游戏（邀上线）。被邀请方接受邀请后，如果游戏正在运行，游戏内会收到TapEventID::RelationGameInviteReceived通知。

TapSDK_Result TapRelation_InviteGame(
    ITapRelation* self
);

参数：

  • self：TapRelation() 返回的好友模块单例对象

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败

TapRelation_InviteTeam​

激活 TapTap 启动器好友邀请窗口，邀请好友加入队伍（邀组队）。被邀请方接受邀请后，如果游戏正在运行，游戏内会收到TapEventID::RelationTeamInviteReceived通知，通知中携带邀请方传入的team_id。

TapSDK_Result TapRelation_InviteTeam(
    ITapRelation* self,
    const TapRelationInviteTeamRequest* request
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • request：邀请好友加入队伍请求参数

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK，表示请求发起失败

使用示例：

TapRelationInviteTeamRequest req{};
req.team_id = "team_abc123"; // ASCII，不能包含空格、双引号、换行符等特殊符号

auto ret = TapRelation_InviteTeam(TapRelation(), &req);
if (ret != TapSDK_Result_OK) {
    return -1;
}

TapRelation_HandleInviteScheme​

通过邀请 scheme 主动触发邀请到达回调，用于被邀请方冷启动游戏的场景。

被邀请方接受邀请时，如果游戏尚未运行，TapTap 启动器会带命令行参数--tap_invite_scheme启动游戏：

your_game.exe --tap_invite_scheme="tds<client_id>://<action>?open_id=...&union_id=...&team_id=..."

SDK 自身无法解析进程命令行参数，需要游戏侧解析到该参数后，把tap_invite_scheme的值原样传入此接口，由 SDK 触发对应事件回调：

  • <action> 为 invite_game → TapEventID::RelationGameInviteReceived
  • <action> 为 invite_team → TapEventID::RelationTeamInviteReceived
TapSDK_Result TapRelation_HandleInviteScheme(
    ITapRelation* self,
    const char* invite_scheme
);

参数：

  • self：TapRelation() 返回的好友模块单例对象
  • invite_scheme：完整的 invite scheme 字符串，不含 --tap_invite_scheme= 前缀

返回值：

  • TapSDK_Result_OK：解析成功并会触发对应回调
  • TapSDK_Result_InvalidArgument：scheme 为空或格式不合法

注意事项：

  • 为了不丢事件，必须在 TapSDK 初始化成功后，立刻注册TapEventID::RelationGameInviteReceived和TapEventID::RelationTeamInviteReceived的回调函数

使用示例：

// 必须在调用 TapRelation_HandleInviteScheme 之前完成事件回调注册，否则会丢事件
TapSDK_RegisterCallback(TapEventID::RelationGameInviteReceived, gameInviteReceivedNotification);
TapSDK_RegisterCallback(TapEventID::RelationTeamInviteReceived, teamInviteReceivedNotification);

const char* inviteScheme =
    "tdsXXXXXXXX://invite_team?open_id=xxx&union_id=yyy&team_id=team_abc123";

auto ret = TapRelation_HandleInviteScheme(TapRelation(), inviteScheme);
if (ret != TapSDK_Result_OK) {
    // scheme 为空或格式不合法
    return -1;
}