User Profile Hosting

This document helps developers understand how to implement user profile subscription, querying, and monitoring in the RC IM iOS Client SDK, along with modifying and querying user profiles and permissions. Through this guide, you'll learn how to retrieve and track user profiles, as well as receive notifications when profile changes or subscription status updates occur.

tip

This feature is supported starting from version 5.10.0.

Enabling the Service

The profile hosting service is enabled by default, allowing you to use user profile hosting functionality directly.

Managing User Profiles

The RC IMLib SDK provides interfaces for querying user profiles, subscribing to updates, and modifying your own profile information.

Setting User Profiles

Use the updateMyUserProfile:success:error: interface to modify your profile. Configure relevant profile attributes by creating an RCUserProfile object.

Interface Prototype

- (void)updateMyUserProfile:(RCUserProfile *)profile
               successBlock:(void (^)(void))successBlock
                 errorBlock:(nullable void (^)(RCErrorCode errorCode,  NSArray<NSString *> * _Nullable errorKeys))errorBlock;


#### Parameter Description
[RCUserProfile] Attributes:

| Attribute       | Type          | Description     |
| -------------- | ------------ | -------- |
| name           | NSString     | Nickname (max 32 characters). |
| portraitUri    | NSString     | Avatar URL (max 128 characters). |
| uniqueId       | NSString     | User application ID (supports alphanumeric characters, max 32 characters). **Note**: Client SDK does not support setting this field. |
| email          | NSString     | Email (max 128 characters).|
| birthday       | NSString     | Birthday (max 32 characters). |
| gender         | RCUserGender | Gender.|
| location       | NSString     | Location (max 32 characters). |
| role           | NSUInteger   | Role (supports values 0-100). |
| level          | NSUInteger   | Level (supports values 0-100). |
| userExtProfile | `NSDictionary<NSString *, NSString *>`  | Custom extended information (max 20 key-value pairs). Keys must be preconfigured in the developer console.<ol><li>Key: Alphanumeric (max 32 characters), must be unique per AppKey. Returns error if key doesn't exist.</li><li>Value: String (max 256 characters).</li></ol> |


#### Example Code

```objectivec
RCUserProfile *userProfile = [[RCUserProfile alloc] init];
userProfile.name = @"name";

[[RCCoreClient sharedCoreClient] updateMyUserProfile:userProfile success:^{
    // Update successful
} error:^(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys) {
    // Update failed
    // When errorCode == RC_SERVICE_INFORMATION_AUDIT_FAILED, errorKeys returns rejected attributes (e.g., name)
}];


### Retrieving Current User Profile

Use `getMyUserProfile:error:` to fetch your own profile.


#### Example Code

```objectivec
[[RCCoreClient sharedCoreClient] getMyUserProfile:^(RCUserProfile *userProfile) {
    // Retrieval successful
} error:^(RCErrorCode errorCode) {
    // Retrieval failed
}];


### Batch Retrieving Other Users' Profiles

Use `getUserProfiles:success:error:` to query profiles of specified users by their userIds.
:::tip


- Maximum 20 users per query.
:::


#### Example Code

```objectivec
NSArray *userIds = @[@"userId1", @"userId2"];
[[RCCoreClient sharedCoreClient] getUserProfiles:userIds success:^(NSArray<RCUserProfile *> *userProfiles) {
    // Retrieval successful
} error:^(RCErrorCode errorCode) {
    // Retrieval failed
}];


## Managing User Permissions

The RC IMLib SDK provides interfaces for setting and retrieving user-level permissions via the `RCUserProfileVisibility` enum.

[RCUserProfileVisibility] Enum Values

| Enum Value | Permission |
| -------------------------------- |-------------------------------|
| RCUserProfileVisibilityNotSet    | Not Set: Follows AppKey-level permissions (default).   |
| RCUserProfileVisibilityInvisible | Invisible: Others can only see name and avatar. |
| RCUserProfileVisibilityEveryone  | Everyone: All users under the AppKey can view your profile.      |


### Permission Rules

Default AppKey-level permission is **Invisible**, and default user-level permission is **Not Set**. When both are unconfigured (default), only usernames and avatars are visible.

Combined permission behavior:

| AppKey-Level Permission | User-Level Permission | Result |
| ------------------------- |-------------------------------|----|
| Invisible/Friends/Everyone | Not Set   | Follows AppKey-level setting   |
| Invisible/Friends/Everyone | Configured (Invisible/Friends/Everyone) |   Follows user-level setting  |


### Setting Permissions

Use `updateMyUserProfileVisibility:success:error` to configure your profile visibility.


#### Example Code

```objectivec
[[RCCoreClient sharedCoreClient] updateMyUserProfileVisibility:RCUserProfileVisibilityEveryone success:^{
    // Update successful
} error:^(RCErrorCode errorCode) {
    // Update failed
}];


### Retrieving Permissions

Use `getMyUserProfileVisibility:` to check your current visibility settings.


#### Example Code

```objectivec
[[RCCoreClient sharedCoreClient] getMyUserProfileVisibility:^(RCUserProfileVisibility visibility) {
    // Retrieval successful
} error:^(RCErrorCode errorCode) {
    // Retrieval failed
}];


## Searching Users


### Exact Search by Application ID

Use `searchUserProfileByUniqueId:success:error` to search users by their unique application ID:


#### Example Code
```objectivec
// Query by application ID
[[RCCoreClient sharedCoreClient] searchUserProfileByUniqueId:@"uniqueId" success:^(RCUserProfile * _Nonnull userProfile) {
    // Query successful
} error:^(RCErrorCode errorCode) {
    // Query failed
}];


## User Profile & Permission Change Subscriptions


### Monitoring Subscription Events

To receive real-time notifications for subscription changes, set up the subscription event delegate after initializing the IMLib SDK but before establishing a connection. Implement the `RCSubscribeEventDelegate` protocol methods.

```objectivec
// Add delegate
[[RCCoreClient sharedCoreClient] addSubscribeEventDelegate:self];

// Remove delegate
[[RCCoreClient sharedCoreClient] removeSubscribeEventDelegate:self];
:::tip


- Starting from v5.10.0, RCSubscribeType includes:
  RCSubscribeTypeOnlineStatus(1) and RCSubscribeTypeUserProfile(2).


- Starting from v5.12.0, RCSubscribeType adds:
  RCSubscribeTypeFriendOnlineStatus(3) and RCSubscribeTypeFriendUserProfile(4).
:::

Delegate Implementation:


```objectivec
/// Deprecated, please use onSubscriptionSyncCompleted: instead
- (void)onSubscriptionSyncCompleted;

/// Subscription data synchronization completed
/// Use type to distinguish between different subscription types. When equal to RCSubscribeTypeOnlineStatus, it represents an online status subscription event.
/// - Since: 5.10.0
- (void)onSubscriptionSyncCompleted:(RCSubscribeType)type;

2. When subscription events change, you can implement this method to handle the changes, such as updating the user interface or processing new data. Typically, this method is called in a background thread, so you need to switch to the main thread to update the UI. subscribeEvents is a list of subscription events containing all changed events. Note: There is no notification for subscription expiration, so you need to monitor the expiration time yourself.

   /// Note: Starting from version 5.10.0, you need to check the subscribeType of RCSubscribeInfoEvent. When equal to RCSubscribeTypeOnlineStatus, it represents an online status subscription event.
   - (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents;

3. When a user's subscription information changes on another device, you can update the status information on the current device in this method to ensure consistency of subscription information. subscribeEvents contains a list of changed subscription events.

   /// Starting from version 5.10.0, you need to check the subscribeType of RCSubscribeEvent. When equal to RCSubscribeTypeOnlineStatus, it represents an online status subscription event.
   - (void)onSubscriptionChangedOnOtherDevices:(NSArray<RCSubscribeEvent *> *)subscribeEvents;

Subscribing to User Information & Permission Changes

When you need to track changes in other users' information and permissions, you can use the subscribeEvent:completion: method to subscribe to user information change events.

1. You need to create a subscription request object RCSubscribeEventRequest, set the subscription type to user information and permission change status RCSubscribeTypeUserProfile, and configure the list of user IDs to be subscribed and the subscription duration. Note that you can subscribe to a maximum of 200 users at a time, with a total limit of 1,000 subscribed users, and you can be subscribed by up to 5,000 users.

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
// List of users to subscribe to
request.userIds = @[@"userId1", @"userId2"];
// Subscription type
request.subscribeType = RCSubscribeTypeUserProfile;
// Subscription duration in seconds
request.expiry = 180000;

2. Call the subscribeEvent:completion: method with the RCSubscribeEventRequest object configured in the first step to execute the subscription.

[[RCCoreClient sharedCoreClient] subscribeEvent:request completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
    if (RC_SUCCESS == status) {
        // Subscription successful
    }
}];

Unsubscribing from User Information & Permission Changes

1. When you no longer need to track changes in subscribed users' information and permissions, create a subscription request object RCSubscribeEventRequest, set the subscription type to user information and permission change status RCSubscribeTypeUserProfile, and configure the list of user IDs to unsubscribe. Note that you can unsubscribe from a maximum of 200 users at a time.

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeUserProfile;
request.userIds = @[@"userId1", @"userId2"];

2. Call the unSubscribeEvent:completion: method with the RCSubscribeEventRequest object configured in the first step to unsubscribe from the specified users' information and permission changes.

[[RCCoreClient sharedCoreClient] unSubscribeEvent:request completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
    if (RC_SUCCESS == status) {
        // Unsubscription successful
    }
}];

Querying Subscription Status for User Information & Permission Changes

1. When you need to query the subscription status for specific users' information and permission changes, create a subscription request object RCSubscribeEventRequest, set the subscription type to user information and permission change status RCSubscribeTypeUserProfile, and configure the list of user IDs to query. Note that you can query a maximum of 200 users at a time.

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeUserProfile;
request.userIds = @[@"userId1", @"userId2"];

2. Call the querySubscribeEvent:completion: method with the RCSubscribeEventRequest object configured in the first step to query the subscription status for the specified users.

[[RCCoreClient sharedCoreClient] querySubscribeEvent:request completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
    if (RC_SUCCESS == status) {
        // Query successful
    }
}];

Paginated Query of Subscription Status for User Information & Permission Changes

1. When you need to paginate query all subscribed users' information and permission changes, create a subscription request object RCSubscribeEventRequest and set the subscription type to user information and permission change status RCSubscribeTypeUserProfile.

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeUserProfile;

2. Call the querySubscribeEvent:pageSize:startIndex:completion: method with the RCSubscribeEventRequest object configured in the first step, and set the starting index and the number of users per page.

• pageSize: The number of users per page, ranging from [1~200].
• startIndex: The starting index. For the first page, pass 0. For the next page, use the total number of users already retrieved (e.g., if pageSize = 20, when querying the second page, you have already retrieved 20 users from the first page, so set startIndex to 20; when querying the third page, you have retrieved 40 users from the first two pages, so set startIndex to 40).

[[RCCoreClient sharedCoreClient] querySubscribeEvent:request 
                                            pageSize:20 
                                          startIndex:0 
                                          completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
    if (RC_SUCCESS == status && subscribeEvents.count > 0) {
        // Query successful
    }
}];