Visitor Mode - social.plus

Visitor mode lets anonymous users browse public content read-only, without signing in. Access is controlled server-side to protect platform integrity.

Visitor mode is not enabled by default. To enable visitor mode for your network, please contact support@social.plus 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 support@social.plus 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: 403999
ServerError.BOT_PERMISSION_DENIED: 403998

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

Daily Usage Limit

Visitor and bot users share a daily read request quota. Once the quota is exhausted, all subsequent read API calls return error code 400323 until the quota resets.

Quota: 100 read requests per day, shared across all API endpoints — feed, events, communities, user profiles, etc. The counter resets daily. Monthly overages are a billing concern only; the SDK never receives a monthly-limit error.

Error Code

Error Constant	Code	Trigger
`VISITOR_USAGE_LIMIT_EXCEEDED`	`400323`	Visitor/bot has exhausted their daily read quota
`VISITOR_PERMISSION_DENIED`	`403999`	Visitor attempted a write operation
`BOT_PERMISSION_DENIED`	`403998`	Bot attempted a restricted operation

SDK Event Subscription

The SDK emits a visitorUsageLimitReached event the first time error 400323 is detected per session. Subsequent failures within a 2-second window are deduplicated to avoid triggering the handler on simultaneous parallel requests.

iOS
Android
TypeScript

// Subscribe to usage limit events after visitor login
let cancellable = AmityClient.shared.getVisitorUsageLimitEvents()
    .receive(on: DispatchQueue.main)
    .sink { event in
        // Navigate to sign-in or show custom error UI
        print("Visitor usage limit reached for user: \(event.userId)")
    }

// Subscribe to usage limit events after visitor login
AmityCoreClient.getVisitorUsageLimitEvents()
    .observeOn(AndroidSchedulers.mainThread())
    .doOnNext { event ->
        // Navigate to sign-in or show custom error UI
        Log.d("Visitor", "Usage limit reached for user: ${event.userId}")
    }
    .subscribe()

import { onVisitorUsageLimitReached } from '@amityco/ts-sdk';

// Subscribe to usage limit events after visitor login
const unsubscribe = onVisitorUsageLimitReached(() => {
    // Navigate to sign-in or show custom error UI
    console.log('Visitor usage limit reached');
});

// Unsubscribe when cleaning up
// unsubscribe();

The event is only emitted for VISITOR and BOT user types. Signed-in users never receive this event.

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

Troubleshooting

Visitor login fails with permission error

Symptoms: Cannot login as visitor, permission denied errorsSolutions:

Verify visitor mode is enabled - Contact support@social.plus 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

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

​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

​Daily Usage Limit

​Error Code

​SDK Event Subscription

​Data Management & Lifecycle

​Guest User Data Cleanup

​Implementation Best Practices

​Visitor Mode Strategy

​Security Considerations

​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

Daily Usage Limit

Error Code

SDK Event Subscription

Data Management & Lifecycle

Guest User Data Cleanup

Implementation Best Practices

Visitor Mode Strategy

Security Considerations

Troubleshooting

Next Steps