API Reference

Notes

Initialization required

Before calling any friend module API function, you must successfully call TapSDK_Init first. If not initialized or initialization fails, friend module function calls will return errors or unexpected results.

String encoding

All string parameters (char*) accepted and returned by friend module APIs are UTF-8 encoded. Convert as appropriate for your project.

User authorization

• The friend module requires the user to grant the user_friends scope. Calls without authorization will return an authorization error.
• You can first call TapUser_AsyncGetApprovedScopes() to check the user's currently granted scopes. Only when user_friends is not in the granted scopes do you need to call TapUser_AsyncAuthorize("user_friends") to request friend info authorization.

Data type definitions

Enums

TapRelation_SyncRelationshipActionType

Action type for syncing friend relationships:

enum {
    TapRelation_SyncRelationshipActionType_Add = 0,    // Add a friend relationship
    TapRelation_SyncRelationshipActionType_Remove = 1, // Remove a friend relationship
};
typedef uint32_t TapRelation_SyncRelationshipActionType;

Structs

Byte alignment

All structs used by the friend module use 8-byte alignment: #pragma pack(push, 8).

TapRelationFollowStatus

Follow relationship:

typedef struct {
    bool following;  // Whether the current user follows the other party
    bool followed;   // Whether the current user is followed by the other party (fan)
    bool blocking;   // Whether the current user has blocked the other party
    bool blocked;    // Whether the current user is blocked by the other party
} TapRelationFollowStatus;

TapRelationFriendInfo

Friend info:

typedef struct {
    const char* open_id;  // Friend's OpenID
    const char* name;     // Username
    const char* alias;    // Alias (note name)
    const char* avatar;   // Avatar URL
    TapRelationFollowStatus follow_status;
    int64_t created_at;   // Relationship creation timestamp, seconds since 1970
} TapRelationFriendInfo;

TapRelationGetFriendListRequest

Request for fetching the friend list (mutual follows), used with TapRelation_AsyncGetFriendList():

typedef struct {
    const char* continuation_token; // Token used for fetching the next page. Pass NULL for the first page
} TapRelationGetFriendListRequest;

TapRelationGetFriendListResponse

Callback data for TapRelation_AsyncGetFriendList(), delivered via TapEventID::RelationGetFriendList:

typedef struct {
    int64_t                       request_id;          // Request ID. Returned as-is from the developer's async call
    const TapSDK_Error*           error;               // Error info. NULL means success; non-NULL means the request failed
    uint32_t                      friend_count;        // Length of the friends array
    const TapRelationFriendInfo*  friends;             // Mutual friend list
    const char*                   continuation_token;  // Token for the next page; NULL if no next page
} TapRelationGetFriendListResponse;

TapRelationGetFollowingListRequest

Request for fetching the following list (users I follow), same shape as TapRelationGetFriendListRequest:

typedef TapRelationGetFriendListRequest TapRelationGetFollowingListRequest;

TapRelationGetFollowingListResponse

Callback data for TapRelation_AsyncGetFollowingList(), delivered via TapEventID::RelationGetFollowingList:

typedef struct {
    int64_t                       request_id;
    const TapSDK_Error*           error;
    uint32_t                      following_count;     // Length of the followings array
    const TapRelationFriendInfo*  followings;          // List of users I follow
    const char*                   continuation_token;  // Token for the next page; NULL if no next page
} TapRelationGetFollowingListResponse;

TapRelationGetFanListRequest

Request for fetching the fan list (users who follow me), same shape as TapRelationGetFriendListRequest:

typedef TapRelationGetFriendListRequest TapRelationGetFanListRequest;

TapRelationGetFanListResponse

Callback data for TapRelation_AsyncGetFanList(), delivered via TapEventID::RelationGetFanList:

typedef struct {
    int64_t                       request_id;
    const TapSDK_Error*           error;
    uint32_t                      fan_count;           // Length of the fans array
    const TapRelationFriendInfo*  fans;                // Fan list
    const char*                   continuation_token;  // Token for the next page; NULL if no next page
} TapRelationGetFanListResponse;

TapRelationShowUserProfileRequest

Request for showing the user card, used with TapRelation_ShowUserProfile():

typedef struct {
    const char* open_id;  // User OpenID
    const char* union_id; // User UnionID. Mutually exclusive with open_id; passing both returns an error
} TapRelationShowUserProfileRequest;

TapRelationSyncRelationshipWithOpenIDRequest

Request for syncing friend relationships by OpenID, used with TapRelation_AsyncSyncRelationshipWithOpenID():

typedef struct {
    TapRelation_SyncRelationshipActionType action;
    const char* nickname;        // Your own nickname. NULL and empty strings are not allowed
    const char* friend_nickname; // Friend's nickname. NULL and empty strings are not allowed
    const char* friend_open_id;  // Friend's OpenID
} TapRelationSyncRelationshipWithOpenIDRequest;

TapRelationSyncRelationshipWithUnionIDRequest

Request for syncing friend relationships by UnionID, used with TapRelation_AsyncSyncRelationshipWithUnionID():

typedef struct {
    TapRelation_SyncRelationshipActionType action;
    const char* nickname;        // Your own nickname. NULL and empty strings are not allowed
    const char* friend_nickname; // Friend's nickname. NULL and empty strings are not allowed
    const char* friend_union_id; // Friend's UnionID
} TapRelationSyncRelationshipWithUnionIDRequest;

TapRelationSyncRelationshipResponse

Callback data for syncing friend relationships, delivered via TapEventID::RelationSyncRelationshipWithOpenID or TapEventID::RelationSyncRelationshipWithUnionID:

typedef struct {
    int64_t              request_id;
    const TapSDK_Error*  error; // NULL means success; non-NULL means the request failed
} TapRelationSyncRelationshipResponse;

TapRelationInviteTeamRequest

Request for inviting a friend to join a team, used with TapRelation_InviteTeam():

typedef struct {
    const char* team_id; // Team parameter. Must be ASCII; cannot contain spaces, double quotes, line breaks, or other special characters
} TapRelationInviteTeamRequest;

TapRelationInviteReceivedNotification

• After the invitee accepts the invitation, if the game is running, the game receives this event notification.
• Accepting an "invite to game" maps to TapEventID::RelationGameInviteReceived; accepting an "invite to team" maps to TapEventID::RelationTeamInviteReceived.

typedef struct {
    const char* open_id;  // OpenID of the friend who sent the invitation
    const char* union_id; // UnionID of the friend who sent the invitation
    const char* team_id;  // Only valid for team invitations (RelationTeamInviteReceived); NULL for invite-to-game
} TapRelationInviteReceivedNotification;

TapRelationUnreadMessageCountNotification

Unread message count change notification, delivered via TapEventID::RelationUnreadMessageCountChanged:

typedef struct {
    uint32_t count; // Latest unread message count
} TapRelationUnreadMessageCountNotification;

TapRelationNewFanCountNotification

New fan count change notification, delivered via TapEventID::RelationNewFanCountChanged. Same shape as TapRelationUnreadMessageCountNotification:

typedef TapRelationUnreadMessageCountNotification TapRelationNewFanCountNotification;

ITapRelation

Friend module interface object, obtained via TapRelation():

typedef struct ITapRelation ITapRelation;

Functions

TapRelation

Get the friend module singleton.

ITapRelation* TapRelation();

Returns:

• The friend module singleton object

Example:

ITapRelation* relation = TapRelation();

TapRelation_AsyncGetFriendList

Issue an async request to fetch the mutual-follow friend list. On a successful start, the result is delivered via the TapEventID::RelationGetFriendList event.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• request_id: a developer-generated request ID, returned as-is in the callback to correlate with the original request
• request: friend-list request parameters; NULL is not allowed

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start and no callback will fire

Example:

TapRelationGetFriendListRequest req{};
req.continuation_token = nullptr; // NULL for the first page; pass the token returned by the previous callback for subsequent pages

auto ret = TapRelation_AsyncGetFriendList(
    TapRelation(),
    ++gRequestID,
    &req);
if (ret != TapSDK_Result_OK) {
    // Request failed to start; no callback will fire
    return -1;
}

TapRelation_AsyncGetFollowingList

Issue an async request to fetch the following list (users I follow). On a successful start, the result is delivered via the TapEventID::RelationGetFollowingList event.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• request_id: a developer-generated request ID, returned as-is in the callback
• request: following-list request parameters; NULL is not allowed

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start and no callback will fire

TapRelation_AsyncGetFanList

Issue an async request to fetch the fan list (users who follow me). On a successful start, the result is delivered via the TapEventID::RelationGetFanList event.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• request_id: a developer-generated request ID, returned as-is in the callback
• request: fan-list request parameters; NULL is not allowed

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start and no callback will fire

TapRelation_AsyncSyncRelationshipWithOpenID

Issue an async request to sync friend relationships by OpenID. On a successful start, the result is delivered via the TapEventID::RelationSyncRelationshipWithOpenID event.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• request_id: a developer-generated request ID, returned as-is in the callback
• request: sync-relationship request parameters; NULL is not allowed

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start and no callback will fire

Example:

TapRelationSyncRelationshipWithOpenIDRequest req{};
req.action = TapRelation_SyncRelationshipActionType_Add;
req.nickname = "My in-game nickname";
req.friend_nickname = "Friend's in-game nickname";
req.friend_open_id = "friend_open_id";

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

TapRelation_AsyncSyncRelationshipWithUnionID

Issue an async request to sync friend relationships by UnionID. On a successful start, the result is delivered via the TapEventID::RelationSyncRelationshipWithUnionID event.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• request_id: a developer-generated request ID, returned as-is in the callback
• request: sync-relationship request parameters; NULL is not allowed

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start and no callback will fire

TapRelation_GetUnreadMessageCount

Synchronously get the current unread message count.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• count: out parameter. On success (returns TapSDK_Result_OK), the current total unread message count is written; otherwise it is not modified

Returns:

• TapSDK_Result: TapSDK_Result_OK means success

Notes:

• It's recommended to track unread message count changes in real time by listening to the TapEventID::RelationUnreadMessageCountChanged event. Do not call this API frequently.

TapRelation_GetNewFanCount

Synchronously get the current new fan count.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• count: out parameter. On success (returns TapSDK_Result_OK), the current new fan count is written; otherwise it is not modified

Returns:

• TapSDK_Result: TapSDK_Result_OK means success

Notes:

• It's recommended to track new fan count changes in real time by listening to the TapEventID::RelationNewFanCountChanged event. Do not call this API frequently.

TapRelation_ShowIM

Activate the TapTap launcher's friend chat window where the player can send messages to friends, manage friends, etc.

TapSDK_Result TapRelation_ShowIM(
    ITapRelation* self
);

Parameters:

• self: the friend module singleton returned by TapRelation()

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start

TapRelation_ShowUserProfile

Activate the TapTap launcher's user card window to display the specified user's basic info.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• request: user-card request parameters. open_id and union_id are mutually exclusive; passing both returns an error

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start

Example:

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

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

TapRelation_InviteGame

Activate the TapTap launcher's invite window to invite a friend to launch the game (invite to game). After the invitee accepts, if the game is running, the game receives a TapEventID::RelationGameInviteReceived notification.

TapSDK_Result TapRelation_InviteGame(
    ITapRelation* self
);

Parameters:

• self: the friend module singleton returned by TapRelation()

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start

TapRelation_InviteTeam

Activate the TapTap launcher's invite window to invite a friend to join a team (invite to team). After the invitee accepts, if the game is running, the game receives a TapEventID::RelationTeamInviteReceived notification carrying the team_id passed by the inviter.

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

Parameters:

• self: the friend module singleton returned by TapRelation()
• request: invite-to-team request parameters

Returns:

• TapSDK_Result: if it's not TapSDK_Result_OK, the request failed to start

Example:

TapRelationInviteTeamRequest req{};
req.team_id = "team_abc123"; // ASCII; cannot contain spaces, double quotes, line breaks, or other special characters

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

TapRelation_HandleInviteScheme

Actively trigger the invitation-received callback through an invite scheme — used for the cold-start scenario on the invitee's side.

When the invitee accepts an invitation while the game is not running, the TapTap launcher launches the game with the --tap_invite_scheme command-line argument:

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

The SDK itself cannot parse process command-line arguments. The game side needs to parse this argument and pass the value of tap_invite_scheme as-is to this API. The SDK then triggers the corresponding event callback:

• <action> is invite_game → TapEventID::RelationGameInviteReceived
• <action> is invite_team → TapEventID::RelationTeamInviteReceived

TapSDK_Result TapRelation_HandleInviteScheme(
    ITapRelation* self,
    const char* invite_scheme
);

Parameters:

• self: the friend module singleton returned by TapRelation()
• invite_scheme: the full invite scheme string, without the --tap_invite_scheme= prefix

Returns:

• TapSDK_Result_OK: parsed successfully and the corresponding callback will fire
• TapSDK_Result_InvalidArgument: scheme is empty or malformed

Notes:

• To avoid losing events, you must register callbacks for TapEventID::RelationGameInviteReceived and TapEventID::RelationTeamInviteReceived immediately after TapSDK initialization succeeds.

Example:

// Event callbacks must be registered BEFORE calling TapRelation_HandleInviteScheme, otherwise events will be lost
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 is empty or malformed
    return -1;
}