Visitor Mode
Overview
Visitor mode allows users who have not joined a Community to temporarily access a public Community as a "visitor", browsing Community content only without becoming a formal member. Visitors can get the community profile, member count, channel list, and the visible message list configured by community administrators, but cannot send messages or perform any management operations.
With visitor mode, developers can allow users who have not joined a Community to "browse" Community content first, lowering the barrier to entry. It is suitable for scenarios such as community preview, public content display, and guest browsing.
Prerequisites
- Refer to Send and receive messages to obtain the ZIM SDK, initialize it, and log in to a user.
- Refer to Token authentication to implement user authentication login.
- The Community feature requires ZIM SDK 3.0.0 or later, and visitor mode requires ZIM SDK 3.2.0 or later.
- The Community feature is a premium edition feature. Contact ZEGOCLOUD Technical Support for activation before use.
- Tokens for the Community feature are generated in the same way as for other ZIM features; no additional permission declaration is required.
Visitor Identity
The visitor identity is a logical identity, different from the Role of community members (owner, admin, regular member). When a user accesses a Community as a visitor, most APIs have corresponding restrictions, and visitors have "browse-only" access to Community content.
Visible Message Range for Visitors
After a visitor enters a Community, the visible message range that can be browsed follows these rules:
- The Community owner (with a Role of
1) and admins (with a Role of2) can set the number and time range of messages visible to visitors through the Update the number of visible messages for visitors and Update the visible message time range for visitors APIs. - The intersection of the "number" and "time range" of messages sent before the visitor joins the Community is the messages actually visible to visitors.
Visitor Heartbeat Limits
| Limit Item | Limit Value |
|---|---|
| Maximum concurrent visitor instances (visitor heartbeats) per user | 10 (default), expandable to 20 |
| Interval of a single visitor heartbeat packet | 10 seconds |
| Timeout of a single visitor heartbeat | 120 seconds |
| Removal from the visitor list upon heartbeat timeout | Automatically removed after 12 consecutive heartbeat timeouts |
Capabilities Available to Visitors
Visitors can only browse Community content. The available and unavailable capabilities are as follows:
| Capability | Available to Visitors | Description |
|---|---|---|
| Get community profile | Yes | Such as community name, avatar, notice, member count, etc. |
| Get community attributes | Yes | Read-only, cannot be modified |
| Get channel list | Yes | Public channels can be browsed |
| Get channel profile / attributes | Yes | Read-only |
| Fetch channel messages | Yes | Only within the visible message range |
| Query message reactions | Yes | The reaction list and details can be viewed |
| Query status message list | Yes | Read-only |
| Query member information | Yes | Used to display message bubble related content |
| Send messages / signaling messages | No | Visitors have a read-only identity |
| Create / dismiss a Community | No | - |
| Invite / remove members | No | - |
| Modify community / channel profile and attributes | No | - |
| Set mute / member roles / transfer ownership | No | - |
| Edit / recall messages, message reactions | No | - |
Enter a Community as a Visitor
After logging in to the ZIM SDK, call the enterCommunityAsVisitor API and pass in the target community ID to enter the Community as a visitor. After entering successfully, you can get the full information of the Community through the callback.
- If the user is already a formal member of the Community, there is no need to enter as a visitor; the call returns the error code
6001006in this case. - If the user is already in the Community as a visitor, repeated calls return the error code
6001081.
import im.zego.zim.ZIM;
import im.zego.zim.callback.ZIMCommunityAsVisitorEnteredCallback;
import im.zego.zim.entity.ZIMCommunityFullInfo;
import im.zego.zim.entity.ZIMError;
import im.zego.zim.enums.ZIMErrorCode;
String communityID = "community_001";
zim.enterCommunityAsVisitor(communityID, new ZIMCommunityAsVisitorEnteredCallback() {
@Override
public void onCommunityAsVisitorEntered(ZIMCommunityFullInfo communityInfo, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// Entered successfully, communityInfo contains the full community information
}
}
});Leave a Community as a Visitor
After entering a Community as a visitor, you can call the quitCommunityAsVisitor API to leave the Community actively. After leaving, the community cache and browsing records under the visitor identity are cleared.
Calling this API again after the visitor has left the Community returns the error code 6001082.
zim.quitCommunityAsVisitor(communityID, new ZIMCommunityAsVisitorQuitCallback() {
@Override
public void onCommunityAsVisitorQuit(String communityID, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// Left successfully
}
}
});Converting a Visitor to a Formal Member
The visitor identity is a temporary "browse-only" identity. After a user becomes a community member through the formal joining process, the SDK automatically converts the local visitor status to the formal member status. Developers do not need to call quitCommunityAsVisitor first, and the identity cannot be changed by the client itself.
Conversion Scenarios
| Scenario | Developer Action | Conversion Timing |
|---|---|---|
The Community joinMode is ANY | Call joinCommunity | After joinCommunity succeeds, the SDK receives the formal community data and automatically converts the visitor to a formal member |
The Community joinMode is AUTH | Call sendCommunityJoinApplication | The user remains a visitor before approval; after approval, the conversion happens automatically when the SDK receives the join event or the community list sync data |
The Community joinMode is FORBID | Do not display the join entry | Conversion does not occur |
Sample code: visitor conversion in ANY mode
String communityID = "community_001";
zim.joinCommunity(communityID, new ZIMCommunityJoinedCallback() {
@Override
public void onCommunityJoined(ZIMCommunityFullInfo communityInfo, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// Conversion succeeded, and you can refresh to the formal member UI
}
}
});- If the user is already a formal member, there is no need to call
enterCommunityAsVisitoragain;6001006is returned in this case. - Repeatedly calling
enterCommunityAsVisitorwhen the user is already a visitor returns6001081. - The user remains a visitor before the application is approved; after approval, there is no need to call
quitCommunityAsVisitorfirst, and the SDK automatically completes the conversion from visitor status to formal member status.
SDK Behavior After Conversion
- The SDK merges the community and channel data cached during the visitor period, and switches to the heartbeat and data synchronization of a formal member.
- The SDK clears the visitor-related caches and browsing records, and subsequent data is fetched as a formal member.
- After conversion, the visitor's "browse-only" restrictions no longer apply. Capabilities such as whether the user can speak are determined by the formal member role and the server-side mute policy.
Recommendations for Developers
- Do not determine the identity locally based on "the user has clicked apply"; rely on server callbacks and query results.
- For the UI switch between visitor status and formal member status, refresh through the
joinCommunitysuccess callback or theonCommunityListChangedevent. - If you want to hide the send entry in visitor status, it is recommended to do so only as UI display; the actual sending permission is restricted by the server, avoiding a local-only gate.
Update the Number of Visible Messages for Visitors
The Community owner or admins can call the updateCommunityVisitorFetchMessageCount API to update the number of "messages sent before entering the Community" that visitors can browse after entering the Community.
- Only the Community owner and admins (with a Role of
1or2) can call this API; calls by regular members return the error code6001007. - The intersection of the "number" and "time range" of messages sent before the visitor joins the Community is the messages actually visible to visitors.
int count = 20; // Number of messages sent before entering the Community that visitors can browse after entering
zim.updateCommunityVisitorFetchMessageCount(count, communityID,
new ZIMCommunityVisitorFetchMessageCountUpdatedCallback() {
@Override
public void onCommunityVisitorFetchMessageCountUpdated(String communityID, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// Updated successfully
}
}
});Update the Visible Message Time Range for Visitors
The Community owner or admins can call the updateCommunityVisitorFetchMessageDuration API to update the time range of "messages sent before entering the Community" that visitors can browse after entering the Community, in seconds.
- Only the Community owner and admins (with a Role of
1or2) can call this API. - The intersection of the "number" and "time range" of messages sent before the visitor joins the Community is the messages actually visible to visitors.
int duration = 86400; // Time range of messages sent before entering the Community that visitors can browse after entering, in seconds
zim.updateCommunityVisitorFetchMessageDuration(duration, communityID,
new ZIMCommunityVisitorFetchMessageDurationUpdatedCallback() {
@Override
public void onCommunityVisitorFetchMessageDurationUpdated(String communityID, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// Updated successfully
}
}
});Visitor Access Restriction Information
The visitor access restriction information of a Community is represented by ZIMCommunityVisitorAccessInfo, which contains the number and time range of messages that visitors can fetch. This information is included as the visitorAccessInfo field in the full community information ZIMCommunityFullInfo, and can be obtained through Enter a Community as a visitor or Query Community Information.
ZIMCommunityVisitorAccessInfo Fields
| Field | Type | Description |
|---|---|---|
| fetchMessageCount | int | Number of messages visitors can fetch |
| fetchMessageDuration | long | Time range of messages visitors can fetch, in seconds |
ZIMCommunityFullInfo.visitorAccessInfo Fields
| Field | Type | Description |
|---|---|---|
| visitorAccessInfo | ZIMCommunityVisitorAccessInfo | Visitor access restriction information of the Community |
Common Error Codes
| Error Code | Description | Solution |
|---|---|---|
| 6000011 | User not registered | Check whether the user has logged in |
| 6001004 | Community does not exist | Check whether the communityID is correct |
| 6001006 | Already a Community member | Formal members do not need to enter as a visitor; access the Community directly |
| 6001007 | Community permission error | The visitor accessed an API without permission, or a non-admin tried to update the visible message configuration for visitors |
| 6001081 | User is already a visitor | The current user is already in the Community as a visitor; do not enter again |
| 6001082 | User is not a visitor | The visitor has left the Community; no need to call the leave API again |
FAQs
Q: What SDK version does visitor mode require? A: Visitor mode requires ZIM SDK 3.2.0 or later.
Q: Can visitors send messages? A: No. Visitors have "browse-only" access to Community content. They can only get the community profile, member count, channel list, and visible message list, and cannot send messages or perform any management operations.
Q: Who can set the range of messages visible to visitors?
A: Only the Community owner (with a Role of 1) and admins (with a Role of 2) can set the number and time range of messages visible to visitors.
Q: How are the messages actually visible to visitors calculated?
A: The conversation message sequence (conv msg seq) of the channel at the moment of accessing the Community is taken as the starting point, and then intersected with the "number of messages" and "time range" set by administrators. The result is the messages actually visible to visitors.
Q: Can the visitor identity and formal member identity coexist? A: The visitor identity is a logical identity, different from the member Role. When a user is already a formal member, there is no need to enter the same Community as a visitor.
Q: How does a visitor become a formal member?
A: Follow the formal joining process according to the Community's joinMode:
ANY: calljoinCommunity, and the conversion happens automatically after success;AUTH: callsendCommunityJoinApplication, and the conversion happens automatically after approval;FORBID: cannot join, and no conversion occurs.
Q: Do visitors need to call quitCommunityAsVisitor to exit visitor status before becoming a formal member?
A: No. After approval or a successful joinCommunity call, the SDK automatically converts the local visitor status to the formal member status, and completes the merge and cleanup of visitor caches. Developers should not switch identities on the client by themselves, and should rely on server callbacks/query results.
