Identify users with String UID

Starting with v1.9.5, IoT SDK supports User Account-based identity, so you can identify a device or user with a string instead of an integer UID. Use this when your application already maintains string-based user accounts, for example an email address or a device serial number, and you want to reuse the same identifier in Agora channels instead of mapping it to an integer UID yourself.

The first time a new user account is used, the SDK requests a server-side mapping from the string account to an integer UID, which can add a small amount of latency to that user's initial join.

Prerequisites

In order to follow this procedure you must have:

Implemented the basic IoT SDK functionality. See Build from scratch.

Enable String UID

Set use_string_uid to true in rtc_service_option_t before you initialize the SDK:

rtc_service_option_t service_opt = {
    .use_string_uid = true
};
int rval = agora_rtc_init(appid, &event_handler, &service_opt);
if (rval < 0) {
    printf("Failed to initialize Agora SDK, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

Once you enable String UID, every client in the channel must join using a user account. You cannot mix integer UID and String UID clients in the same channel.

Join a channel with a user account

Create a connection, then call agora_rtc_join_channel_with_user_account instead of agora_rtc_join_channel:

connection_id_t conn_id = 0;
const char *user_account = "xxxx";

rval = agora_rtc_create_connection(&conn_id);
if (rval < 0) {
    printf("Failed to create connection, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

rval = agora_rtc_join_channel_with_user_account(conn_id, "channel-xxx", user_account, token, &channel_opt);
if (rval < 0) {
    printf("Failed to join channel, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

Look up user information

Once a connection has joined the channel, retrieve information about a peer using either their user account or their integer UID:

agora_rtc_get_user_info_by_user_account: look up a remote user's information by their user account.
agora_rtc_get_user_info_by_uid: look up a remote user's information by their integer UID.

Handle user account events

static void __on_join_channel_success(connection_id_t conn_id, uint32_t uid, int elapsed)
{
LOGI("[conn-%u] Join channel success, uid=%u, elapsed=%dms", conn_id, uid, elapsed);
}

static void __on_user_joined_with_user_account(connection_id_t conn_id, const user_info_t *user, int elapsed_ms)
{
LOGI("[conn-%u] Remote user account %s (uid=%u) joined, elapsed=%dms", conn_id, user->user_account, user->uid, elapsed_ms);
}

static void __on_user_offline_with_user_account(connection_id_t conn_id, const user_info_t *user, int reason)
{
LOGI("[conn-%u] Remote user account %s (uid=%u) left, reason=%d", conn_id, user->user_account, user->uid, reason);
}

static void __on_user_info_updated(connection_id_t conn_id, const user_info_t *user)
{
LOGI("[conn-%u] User account %s (uid=%u) info updated", conn_id, user->user_account, user->uid);
}

on_join_channel_success: the local user account joined successfully.
on_user_joined_with_user_account: a remote user account joined the channel.
on_user_offline_with_user_account: a remote user account left the channel.
on_user_info_updated: a user's account information changed.

Sample code

The IoT SDK package includes a complete String UID example. See the full implementation in hello_rtsa.c:

├── agora_rtsa_sdk  # Agora SDK libraries and header files
└── example
    └── hello_rtsa
        └── hello_rtsa.c  # Join a channel with String UID