Visitor Mode - social.plus

Visitor mode is not enabled by default. To enable visitor mode for your network, please contact [email protected] with your network details.

Overview & Concepts

What is Visitor Mode?

Visitor mode enables anonymous public access to your community, allowing users to browse and discover content without requiring authentication. This feature is ideal for growth funnels, SEO optimization, and public content discovery while maintaining platform security and stability.

Visitor Users

Purpose: Anonymous users who browse public content
Access: Read-only permissions enforced server-side
Tracking: Identified by device fingerprinting
Use Case: Public content discovery, growth funnel

Bot Users

Purpose: Search engine crawlers and automated indexers
Access: Read-only permissions for content indexing
Tracking: Identified by User-Agent analysis
Use Case: SEO optimization, content discoverability

How Visitor Mode Works

Visitor mode uses device fingerprinting to identify anonymous users while maintaining privacy:

Device Identification

Your app generates or retrieves a unique device fingerprint for the anonymous user

Visitor Login

The SDK logs in the user as a visitor using the device fingerprint, with optional secure mode via authSignature

Server-Side Role Assignment

social.plus server assigns the “Visitor” or “Bot” role based on the request (User-Agent for bots)

Read-Only Access

Server-side permissions enforce read-only access, allowing content discovery without modification capabilities

Why Device Fingerprinting? This approach allows tracking unique anonymous visitors for analytics while maintaining privacy. Visitors are restricted to read-only access, protecting community integrity.

User Type Comparison

Understanding the different user types helps you design the right access patterns:

Signed-In Users
Visitor Users
Bot Users

// Full authenticated user with read/write access
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('apiKey', 'apiRegion');

// ... your app setup code

await Client.login({
  userId: 'user-123',
  displayName: 'John Doe',
}, sessionHandler);

Capabilities:

✅ Full read/write access to all features
✅ Real-time event connections (MQTT)
✅ Push notifications
✅ Create posts, comments, reactions
✅ Join communities and follow users

// Anonymous visitor with read-only access
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

await Client.loginAsVisitor({
    sessionHandler,
});

Capabilities:

✅ View public posts and content
✅ Browse public communities
✅ View user profiles
❌ No real-time connections (no MQTT)
❌ No push notifications
❌ Cannot create content or interact
❌ Cannot join communities or follow users

// Search engine crawler with read-only access
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

await Client.loginAsBot();

Capabilities:

✅ Index public content for SEO
✅ View public posts and communities
✅ Separated analytics tracking
❌ No real-time connections
❌ No push notifications
❌ No write operations

Quick Start (Visitor Mode)

Step 1: Initialize the SDK

Start by setting up the social.plus client with your API key:

let client = try! AmityClient(apiKey: "your-api-key", region: .SG)

Step 2: Get Visitor Device ID

Generate or retrieve a unique device identifier for the visitor:

let deviceId = client.getVisitorDeviceId()
print("Device ID: \(deviceId)")

The device ID is automatically generated and cached on first access. This unique identifier is used to track the visitor session.

Authenticate as an anonymous visitor to access public content:

Task { @MainActor in
    do {
        // Simple visitor login (development)
        try await client.loginAsVisitor(
            authSignature: nil,
            authSignatureExpiresAt: nil,
            sessionHandler: visitorSessionHandler
        )
        print("Visitor login successful")
    } catch {
        print("Visitor login failed: \(error)")
    }
}

For search engine crawlers and automated indexers:

TypeScript

try {
    await Client.loginAsBot({ sessionHandler });
    console.log('Bot login successful');
} catch (error) {
    console.error('Bot login failed:', error);
}

Bot login is automatically determined by User-Agent analysis on the server. Use this method when you need explicit bot role assignment.

Step 5: Check User Type

Verify the current user type to adapt your UI accordingly:

let userType = client.currentUserType
switch userType {
case .signedIn:
    print("User is authenticated")
case .visitor:
    print("User is a visitor")
case .bot:
    print("User is a bot")
}

Step 6: Logout

End the visitor session:

do {
    try await client.secureLogout()
} catch {
    /// Handle error from revoking accessToken here
}

Secure Visitor Mode (Production)

For production environments, secure visitor mode adds an extra layer of authentication by requiring cryptographic signatures for visitor sessions. Once secure mode is enabled, all visitor login requests must include a valid auth signature generated by your backend server.

Secure visitor mode is not enabled by default. Even if visitor mode is enabled, secure mode must be enabled separately. Contact [email protected] to enable secure visitor mode for your network.

Getting Your Visitor Secret

After visitor secure mode is enabled for your network, retrieve your visitor application secret from the Console:

Navigate to Settings

Open your social.plus Console and go to Settings → Integrations

Locate Visitor Secret

Scroll to the Visitor Secure Mode Setup section (visible only after visitor secure mode is enabled)

Copy Secret

Create new secret and store it securely in your backend environment variables

Security Best Practice: Never expose your secret in client-side code, mobile apps, or version control. This secret must remain on your backend server only.

Backend Auth Signature Generation

Your backend server must generate time-limited auth signatures using HMAC-SHA256 encryption:

// Complete Express.js backend example
const express = require('express');
const crypto = require('crypto');
require('dotenv').config();

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware to parse JSON request bodies
app.use(express.json());

// Visitor auth signature endpoint
app.post('/api/visitor/auth-signature', async (req, res) => {
  try {
    const { deviceId } = req.body;
    
    // Set expiration (e.g., 1 hour from now)
    const authSignatureExpiresAt = new Date(Date.now() + 3600000).toISOString();
    
    // Create signature using HMAC-SHA256 with your visitor secret
    const message = `deviceId=${deviceId}&authSignatureExpiresAt=${authSignatureExpiresAt}`;
    const authSignature = crypto
      .createHmac('sha256', process.env.SOCIAL_PLUS_VISITOR_APP_SECRET)
      .update(message)
      .digest('hex');
    
    res.json({
      authSignature,
      authSignatureExpiresAt
    });
  } catch (error) {
    console.error('Error generating auth signature:', error);
    res.status(500).json({ error: 'Failed to generate auth signature' });
  }
});

// Start server
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Setup Instructions:

Install dependencies:

npm install express dotenv

Create a .env file in your project root:

SOCIAL_PLUS_VISITOR_APP_SECRET=your_visitor_secret_from_console
PORT=3000

Run the server:

node server.js

How It Works: The signature is created by hashing the device ID and expiration timestamp with your secret key. social.plus servers verify the signature using the same secret, ensuring the request originated from your trusted backend.

Use auth signatures for production visitor sessions: Obtain authSignature via the API implemented in the previous step, and provide the corresponding values to loginAsVisitory() function.

Task { @MainActor in
    do {
        // Get device ID
        let deviceId = client.getVisitorDeviceId()
        
        // Request auth signature from your backend
        let (signature, expiresAt) = try await fetchAuthSignature(deviceId: deviceId)
        
        // Login with secure mode
        try await client.loginAsVisitor(
            authSignature: signature,
            authSignatureExpiresAt: expiresAt,
            sessionHandler: visitorSessionHandler
        )
        print("Secure visitor login successful")
    } catch {
        print("Secure visitor login failed: \(error)")
    }
}

Session Handler for Token Renewal

Implement session handlers to automatically refresh auth signatures:

iOS
Android
TypeScript

class VisitorSessionHandler: AmitySessionHandler {
    func sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
        let deviceId = client.getVisitorDeviceId()
        
        // Fetch new auth signature from your backend
        AuthService.shared.fetchVisitorAuthSignature(deviceId: deviceId) { result in
            switch result {
            case .success(let authData):
                renewal.renewWithAuthSignature(
                    authSignature: authData.signature,
                    authSignatureExpiresAt: authData.expiresAt
                )
            case .failure(let error):
                print("Failed to refresh visitor token: \(error)")
                renewal.unableToRetrieveAuthSignature()
            }
        }
    }
}

// Use during visitor login
let sessionHandler = VisitorSessionHandler()
try await client.loginAsVisitor(
    authSignature: signature,
    authSignatureExpiresAt: expiresAt,
    sessionHandler: sessionHandler
)

class VisitorSessionHandler : SessionHandler {
    override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
        val deviceId = AmityCoreClient.getVisitorDeviceId()
        
        // Fetch new auth signature from your backend
        authRepository.fetchVisitorAuthSignature(deviceId) { authData ->
            if (authData != null) {
                renewal.renewWithAuthSignature(
                    authData.signature,
                    authData.expiresAt
                )
            } else {
                renewal.unableToRetrieveAuthSignature()
            }
        }
    }
}

// Use during visitor login
val sessionHandler = VisitorSessionHandler()
AmityCoreClient.loginAsVisitor(object : SessionHandler {
        override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
            renewal.renew()
        }
    })
    .authSignature(signature)
    .authSignatureExpiresAt(expiresAt)
    .build()
    .submit()

const createVisitorSessionHandler = (): Amity.SessionHandler => ({
    sessionWillRenewAccessToken: async (renewal: Amity.AccessTokenRenewal) => {
        try {
            const deviceId = client.getVisitorDeviceId();
            
            // Fetch new auth signature from your backend
            const { authSignature, authSignatureExpiresAt } = 
                await AuthService.fetchVisitorAuthSignature(deviceId);
            
            renewal.renewWithAuthSignature({ authSignature, authSignatureExpiresAt });
        } catch (error) {
            console.error('Failed to refresh visitor token:', error);
            renewal.unableToRetrieveAuthSignature();
        }
    }
});

// Use during visitor login
await Client.loginAsVisitor({
    authSignature,
    authSignatureExpiresAt,
    sessionHandler: createVisitorSessionHandler(),
});

Understanding Visitor Permissions

Visitor and bot users have server-side enforced read-only permissions to protect community integrity:

Allowed Actions ✅

View public posts and content
Browse public communities
View user profiles
View comments and replies
View post reactions
Access public media (images, videos)

Restricted Actions ❌

Create posts or stories
Comment or reply
React to posts/comments
Join communities
Follow/unfollow users
Report content or users
Send messages
Receive push notifications
Real-time event connections (MQTT)

Permission Enforcement

All visitor restrictions are enforced server-side - attempting restricted actions will result in permission errors:

// Error codes for visitor/bot permission denial
ServerError.VISITOR_PERMISSION_DENIED: 488999
ServerError.BOT_PERMISSION_DENIED: 488998

Resource Conservation

Visitors and bots are excluded from resource-intensive features:

Real-Time Events
Push Notifications
User Discovery

MQTT Connection: Disabled for visitors/bots

No real-time event subscriptions
No live updates or notifications
Reduces server load and connection costs
Does not count towards CCU (Concurrent Connection Users) limits

// SDK automatically skips MQTT connection for visitors
const userType = Client.getCurrentUserType();
if (userType === UserTypeEnum.VISITOR || userType === UserTypeEnum.BOT) {
    // mqtt.connect() is NOT called
}

Push Notifications: Blocked for visitors/bots

Cannot register device tokens
Filtered out from notification recipient lists
Applies to all notification types
Prevents unpredictable costs from anonymous audience

// Push notification registration is blocked
if (userType === AmityUserType.VISITOR || userType === AmityUserType.BOT) {
    // registerPushNotification() throws error or no-ops
}

User Listing/Search: Hidden from results

Excluded from user search APIs
Not visible in followers/following lists
Hidden from user discovery features
Maintains authentic member directories

// Visitors are automatically filtered from user queries
// Your queries return only signed-in users
const users = await UserRepository.searchUserByDisplayName({ displayName: 'John' });
// Returns: only SIGNED_IN users, no VISITOR or BOT users

UIKit Visitor Experience

UIKit automatically adapts to visitor mode with optimized navigation and content discovery:

Page Visibility

UIKit shows/hides pages based on user type:

Visitor Mode
Signed-In User

Visible Pages:

✅ Explore (default homepage)
✅ Clips Feed (configurable, hidden by default)

Hidden Pages:

❌ Newsfeed
❌ Notifications
❌ My Communities

// config.json - Clips Feed visibility control
{
  "feature_flags": {
    "post": {
      "clip": {
        "can_create": "signed_in_user_only",  // or "all", "none"
        "can_view_tab": "signed_in_user_only" // or "all", "none"
      }
    }
  }
}

UIKit navigation automatically adjusts based on available pages:

Mobile Navigation

Single Tab Scenario: When only one page is visible (e.g., Explore only)

Top tab navigation bar is hidden
Cleaner, focused single-page experience

Multiple Tabs: When 2+ pages are visible

Top tab navigation bar remains visible
Users can switch between available pages

Desktop Navigation

Sidebar Always Visible: Regardless of page count

Main sidebar navigation always shown
Ensures persistent access to global elements
Includes search bar and other navigation tools
Maintains consistent desktop experience

Visitor Interaction Handling

UIKit provides default behaviors for visitor interaction attempts:

iOS
Android
TypeScript

// Set behavior
AmityUIKit4Manager.behavior.globalBehavior = MyGlobalBehavior()

// Override behavior
class MyGlobalBehavior: AmityGlobalBehavior { 

    override func handleGuestUserAction(context: Context?) {
        // Custom Behavior
    }
    
    override func handleNonMemberAction(context: Context?) {
        // Custom Behavior
    }
    
    override func handleNonFollowerAction(context: Context?) {
        // Custom Behavior
    }
}

AmityUIKit4Manager.behavior.globalBehavior = object: AmityGlobalBehavior() {
    override fun handleVisitorUserAction() {
        // Custom behavior for visitor user action
    }

    override fun handleNonMemberAction() {
        // Custom behavior for non-member action
    }

    override fun handleNonFollowerAction() {
        // Custom behavior for non-follower action
    }
}

// AmityGlobalBehavior - Default visitor interaction handling

const { AmityGlobalBehavior } = usePageBehavior();

// Visitor user
AmityGlobalBehavior.handleGuestUserAction();
// Non-Member user in a community
AmityGlobalBehavior.handleNonMemberAction();
// Non-Follower user of a user
AmityGlobalBehavior.handleNonFollowerAction();

Action Button States

UIKit manages action button visibility based on user type and permissions:

Public Community Actions

Action	Visitor	Non-Member	Member
React to Post	Button visible, action blocked	Button visible, action allowed	Button visible, action allowed
Comment on Post	Button visible, action blocked	Button visible, action allowed	Button visible, action allowed
Reply to Comment	Button visible, action blocked	Button visible, action allowed	Button visible, action allowed
Report Content	Button visible, action blocked	Button visible, action blocked	Button visible, action allowed
Vote in Poll	Button visible, action blocked	Button hidden, join required	Button visible, action allowed

User Profile Actions

Action	Visitor	Signed-In User
React to Post	Button hidden	Button visible, action allowed
Comment on Post	Button visible, action blocked	Button visible, action allowed
Reply to Comment	Button visible, action blocked	Button visible, action allowed
Report Post	Button visible, action blocked	Button visible, action allowed
Follow User	Button visible, action blocked	Button visible, action allowed
Block User	Button visible, action blocked	Button visible, action allowed

Story & Clip Actions

Action	Visitor	Signed-In User
React to Story	Button visible, action blocked	Button visible, action allowed
React to Clip	Button visible, action blocked	Button visible, action allowed
Comment on Clip	Button visible, action blocked	Button visible, action allowed

Livestream Actions

Action	Visitor	Signed-In User
Send Message	Input visible, action blocked	Input visible, action allowed
React to Message	Button visible, action blocked	Button visible, action allowed
Report Message	Button visible, action blocked	Button visible, action allowed

Customizing Visitor Behavior

Override default behaviors to match your app’s UX:

// Example: Custom visitor action handling

 <AmityUIKitProvider
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  configs={config}
  pageBehavior={{
    AmityGlobalBehavior: {
        handleGuestUserAction: () => {
            // Overridable for custom behavior
        },
        handleNonMemberAction: () => {
            // Overridable for custom behavior
        },
        handleNonFollowerAction: () => {
            // Overridable for custom behavior
        },
    }
  }}
>
 <UikitComponent>
</AmityUIKitProvider>

Data Management & Lifecycle

Guest User Data Cleanup

To prevent accumulation of transient visitor data, social.plus automatically cleans up inactive guest users:

Automatic Cleanup Policy

Schedule: Periodic cleanup (configurable, typically 30-60 days)Criteria: Guest users inactive for the defined periodProcess:

Scheduled job runs automatically
Identifies inactive guest user records
Permanently deletes inactive guest data
No manual intervention required

What’s Deleted:

Guest user profile records
Device fingerprint associations
Session history
Any cached visitor data

Data Retention Considerations

Active Visitors: Continuously using visitors retain their dataPrivacy Compliance: Automatic cleanup supports GDPR/privacy regulationsAnalytics Impact: Historical analytics remain unaffectedConversion Tracking: Converted visitors (who signed up) preserve their history

Event Availability: Guest user events are available through existing webhook/event observation mechanisms configured in your social.plus console.

Implementation Best Practices

Visitor Mode Strategy

When to Use Visitor Mode ✅

Recommended Scenarios:

Public Content Discovery
- Community showcases and landing pages
- SEO-optimized public content
- Growth funnel entry points
- Social media linked content
Conversion Optimization
- Allow browsing before signup
- Demonstrate community value
- Reduce friction in user journey
- Track engagement before conversion
SEO & Indexing
- Enable search engine crawling
- Improve content discoverability
- Separate bot traffic from analytics
- Optimize for organic search

Implementation Tips:

Set clear upgrade prompts for interactive features
Track visitor-to-member conversion rates
Monitor guest traffic patterns
Use analytics to optimize conversion flow

When to Require Authentication ❌

Require Sign-In For:

Private/Sensitive Content
- Member-only communities
- Personal conversations
- Restricted content
- Premium features
High-Value Interactions
- Content creation
- Community moderation
- Direct messaging
- Transaction-based features
Compliance Requirements
- Age-restricted content
- Regulated industries
- Terms of service acceptance
- User accountability needs

Security Considerations

Production Security

Always Use Secure Mode in Production:

// ✅ Production: Secure visitor mode with auth signatures
await client.loginAsVisitor(
  authSignature,        // Generated by your backend
  authSignatureExpiresAt, // With proper expiration
  sessionHandler        // With token renewal logic
);

// ❌ Development only: Simple visitor mode
await client.loginAsVisitor(); // No auth signature

Why Secure Mode?

Prevents unauthorized visitor creation
Enables server verification of device identity
Supports automatic token renewal
Maintains audit trail of visitor sessions

Device Fingerprinting Privacy

Privacy-First Approach:

Device IDs are anonymized
No personal information collected
Automatic cleanup of inactive visitors
Compliant with GDPR/CCPA requirements

Best Practices:

Disclose visitor tracking in privacy policy
Provide opt-out mechanisms where required
Use device IDs only for platform functionality
Don’t link device IDs to external identifiers

Performance Optimization

Resource Management

Visitor Mode Reduces Resource Usage:

No Real-Time Connections
- Visitors don’t connect to MQTT
- Reduces concurrent connection load
- Lower bandwidth consumption
- Better scalability for public access
No Push Notifications
- Prevents notification system overhead
- Reduces APNs/FCM API calls
- Avoids costs from anonymous audience
- Focuses notifications on engaged users
Optimized Query Performance
- Visitors excluded from user searches
- Cleaner user discovery results
- Faster query execution
- Better database performance

Conversion Optimization

Encourage Visitor-to-Member Conversion:

// Example: Strategic upgrade prompts
const handleVisitorAction = (action: string) => {
  const userType = client.getCurrentUserType();
  
  if (userType === UserTypeEnum.VISITOR) {
    showUpgradePrompt({
      action,
      message: getContextualMessage(action),
      benefits: [
        'Join the conversation',
        'Create and share content',
        'Connect with community members',
        'Get personalized notifications'
      ]
    });
  }
};

const getContextualMessage = (action: string) => {
  const messages = {
    'react': 'Sign up to react and engage with posts',
    'comment': 'Create an account to join the discussion',
    'follow': 'Sign in to follow users and communities',
    'post': 'Become a member to share your thoughts'
  };
  return messages[action] || 'Sign up to unlock all features';
};

Troubleshooting

Visitor login fails with permission error

Symptoms: Cannot login as visitor, permission denied errorsSolutions:

Verify visitor mode is enabled - Contact [email protected] if visitor mode has not been enabled for your network
Check API key has visitor access permissions
Ensure you’re using correct region endpoint
For secure mode, verify visitor secure mode is enabled for your network
For secure mode, verify auth signature is correctly generated
Check auth signature hasn’t expired

Device ID not persisting across sessions

Symptoms: New device ID generated each session, losing visitor identitySolutions:

Ensure device storage permissions are granted
Check that SDK has access to persistent storage
Verify cache/storage is not being cleared on app restart
For web: check localStorage is enabled and accessible
For mobile: verify keychain/SharedPreferences access

Visitor actions not blocked properly

Symptoms: Visitors can perform restricted actions, permission errors not shownSolutions:

Verify user type detection: client.getCurrentUserType()
Check UIKit version supports visitor mode restrictions
Ensure server-side permissions are properly configured
Update to latest SDK version with visitor mode support
Verify custom behavior overrides aren’t bypassing restrictions

Auth signature verification fails

Symptoms: Secure visitor login fails with invalid signature errorSolutions:

Verify HMAC-SHA256 algorithm is used correctly
Check message format: deviceId=${deviceId}&authSignatureExpiresAt=${authSignatureExpiresAt}
Ensure application secret matches your backend configuration
Verify timestamp format is ISO 8601
Check signature is hex-encoded, not base64
Ensure no extra whitespace in signature or timestamp

UIKit pages not hiding for visitors

Symptoms: Newsfeed, notifications, or other pages visible to visitorsSolutions:

Verify UIKit version supports visitor mode UI adaptations
Check user type is correctly detected in UIKit
Ensure config.json is properly loaded
For clips feed: verify can_view_tab configuration
Clear app cache and restart
Check for custom navigation overrides

Next Steps

Authentication Guide

Learn about authenticated user login and session management

User Management

Understand user profiles and member management

Community Access Control

Configure community permissions and access levels

Analytics & Reporting

Track visitor metrics and conversion analytics in the Console

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

Documentation Index

​Overview & Concepts

​What is Visitor Mode?

Visitor Users

Bot Users

​How Visitor Mode Works

​User Type Comparison

​Quick Start (Visitor Mode)

​Step 1: Initialize the SDK

​Step 2: Get Visitor Device ID

​Step 3: Login as Visitor

​Step 4: Login as Bot (TypeScript Only)

​Step 5: Check User Type

​Step 6: Logout

​Secure Visitor Mode (Production)

​Getting Your Visitor Secret

​Backend Auth Signature Generation

​Secure Visitor Login

​Session Handler for Token Renewal

​Understanding Visitor Permissions

Allowed Actions ✅

Restricted Actions ❌

​Permission Enforcement

​Resource Conservation

​UIKit Visitor Experience

​Page Visibility

​Adaptive Navigation

Mobile Navigation

Desktop Navigation

​Visitor Interaction Handling

​Action Button States

​Customizing Visitor Behavior

​Data Management & Lifecycle

​Guest User Data Cleanup

​Implementation Best Practices

​Visitor Mode Strategy

​Security Considerations

​Performance Optimization

​Troubleshooting

​Next Steps

Authentication Guide

User Management

Community Access Control

Analytics & Reporting

Overview & Concepts

What is Visitor Mode?

How Visitor Mode Works

User Type Comparison

Quick Start (Visitor Mode)

Step 1: Initialize the SDK

Step 2: Get Visitor Device ID

Step 3: Login as Visitor

Step 4: Login as Bot (TypeScript Only)

Step 5: Check User Type

Step 6: Logout

Secure Visitor Mode (Production)

Getting Your Visitor Secret

Backend Auth Signature Generation

Secure Visitor Login

Session Handler for Token Renewal

Understanding Visitor Permissions

Permission Enforcement

Resource Conservation

UIKit Visitor Experience

Page Visibility

Adaptive Navigation

Visitor Interaction Handling

Action Button States

Customizing Visitor Behavior

Data Management & Lifecycle

Guest User Data Cleanup

Implementation Best Practices

Visitor Mode Strategy

Security Considerations

Performance Optimization

Troubleshooting

Next Steps