> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication & Setup

> Configure user authentication and initialize social.plus UIKit in your application

This guide covers user authentication and device registration for social.plus UIKit. Authentication is essential for personalizing the user experience and enabling social features.

<Note>
  **New to social.plus Authentication?** For comprehensive authentication concepts, security patterns, and backend implementation, see the [SDK Authentication Guide](/social-plus-sdk/getting-started/authentication). This guide focuses specifically on UIKit implementation.
</Note>

## Prerequisites

Before setting up authentication, ensure you have:

<CardGroup cols={2}>
  <Card title="API Credentials" icon="key">
    Your API key and region from social.plus Console
  </Card>

  <Card title="UIKit Installed" icon="cube">
    social.plus UIKit installed in your project
  </Card>
</CardGroup>

<Info>
  **Coming from First Steps?** If you followed the [First Steps guide](/uikit/getting-started/first-steps), you've already completed basic authentication. This guide provides comprehensive details and production-ready patterns.
</Info>

***

## Get Your API Credentials

### Access social.plus Console

<Steps>
  <Step title="Visit Console">
    Go to [social.plus Console](https://console.socialplus.com) and sign in to your account.
  </Step>

  <Step title="Navigate to Security">
    In the left sidebar, click **Settings** → **Security**.
  </Step>

  <Step title="Copy Credentials">
    Find your **API Key** and note your **Region**. You'll need both for authentication.
  </Step>
</Steps>

### Regional Configuration

social.plus operates in multiple regions for optimal performance and compliance:

<Tabs>
  <Tab title="United States">
    ```typescript theme={null}
    apiRegion: "us"
    endpoint: "api.us.amity.co"
    ```
  </Tab>

  <Tab title="Europe">
    ```typescript theme={null}
    apiRegion: "eu" 
    endpoint: "api.eu.amity.co"
    ```
  </Tab>

  <Tab title="Singapore">
    ```typescript theme={null}
    apiRegion: "sg"
    endpoint: "api.sg.amity.co"
    ```
  </Tab>
</Tabs>

<Warning>
  **Region Consistency**: Your API region must match the region where your social.plus application was created. Mismatched regions will cause authentication failures.
</Warning>

***

## Authentication Modes

social.plus UIKit supports two authentication modes depending on your security requirements:

<Tabs>
  <Tab title="Development Mode">
    **Quick Setup (API Key Only)**

    Perfect for development, testing, and proof-of-concept applications:

    ```typescript theme={null}
    // Development authentication - API key only
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="us"
      userId="user-123"
      displayName="John Doe"
    >
      {/* Your app */}
    </AmityUiKitProvider>
    ```

    <Note>
      Development mode is great for getting started quickly, but should not be used in production applications.
    </Note>
  </Tab>

  <Tab title="Production Mode">
    **Secure Setup (API Key + Auth Token)**

    Required for production applications with proper backend verification:

    ```typescript theme={null}
    // Production authentication - with auth token
    const getAuthToken = async () => {
      // Get auth token from your secure backend
      const response = await fetch('/api/auth/social-plus-token');
      const { authToken } = await response.json();
      return authToken;
    };

    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="us"
      userId="user-123"
      displayName="John Doe"
      getAuthToken={getAuthToken}
    >
      {/* Your app */}
    </AmityUiKitProvider>
    ```

    <Warning>
      **Auth Token Security**: Auth tokens must be generated by your backend server after verifying the user. Never generate auth tokens on the client side.
    </Warning>
  </Tab>
</Tabs>

<Card title="Learn About Auth Tokens" icon="shield-check" href="/social-plus-sdk/getting-started/authentication#how-auth-tokens-work">
  Understanding auth tokens, server-to-server verification, and backend implementation patterns
</Card>

***

## Device Registration

### Understanding Device Binding

<Warning>
  **Important**: Once registered, a device is permanently tied to a `userId` until explicitly unregistered or inactive for 90+ days. Plan your authentication flow carefully.
</Warning>

When you authenticate a user with social.plus UIKit, you're registering the current device with that user's ID. This device will receive all messages and notifications belonging to that user.

### Platform Implementation

Choose your platform for device registration:

<Tabs>
  <Tab title="iOS">
    ```swift theme={null}
    import AmityUIKit

    // 1. Register device with user (basic)
    AmityUIKitManager.registerDevice(
        withUserId: "user-123",
        displayName: "John Doe"
    )

    // 2. Register device with auth token (production)
    AmityUIKitManager.registerDevice(
        withUserId: "user-123",
        displayName: "John Doe",
        authToken: "auth-token-from-backend"
    )

    // 3. Register for push notifications (optional)
    UIKitManager.registerDeviceForPushNotification("device-token") { isSuccess, error in
        if isSuccess {
            print("Push notifications registered")
        } else {
            print("Push registration failed: \(error?.localizedDescription ?? "")")
        }
    }
    ```

    <Note>
      **Push Notifications**: social.plus UIKit doesn't manage push permission requests or token creation. Your app must handle these and pass the device token.
    </Note>
  </Tab>

  <Tab title="Android">
    ```kotlin theme={null}
    import com.amity.socialcloud.sdk.AmityCoreClient

    // Production login with auth token
    fun login(userId: String, authToken: String) {
        AmityCoreClient.login(
            userId = userId,
            sessionHandler = object : SessionHandler {
                override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
                    renewal.renew()
                }
            }
        ).authToken(authToken)
            .displayName("John Doe")
            .build()
            .submit()
            .subscribeOn(Schedulers.io())
            .doOnComplete {
                // Device registered successfully
                Log.d("Auth", "User logged in successfully")
            }
            .doOnError { error ->
                Log.e("Auth", "Login failed", error)
            }
            .subscribe()
    }
    ```
  </Tab>

  <Tab title="Web/React">
    ```typescript theme={null}
    import React from 'react';
    import { AmityUiKitProvider, AmityUiKitSocial } from '@amityco/ui-kit-open-source';
    import '@amityco/ui-kit-open-source/dist/index.css';

    export default function App() {
      // Function to get auth token from your backend
      const getAuthToken = async () => {
        const authToken = await getAuthTokenFromApi();
        return authToken;
      };
      
      return (
        <AmityUiKitProvider
          key="user-123" // Important: key should match userId
          apiKey="YOUR_API_KEY"
          userId="user-123"
          displayName="John Doe"
          apiRegion="us" // eu, us, or sg
          getAuthToken={getAuthToken} // For secure mode authentication
        >
          <div
            style={{
              position: "absolute",
              left: 0,
              top: 0,
              width: "100vw",
              height: "100dvh",
            }}
          >
            <AmityUiKitSocial />
          </div>
        </AmityUiKitProvider>
      );
    }
    ```

    <Warning>
      **Provider Placement**: `AmityUiKitProvider` should be placed only once at the top of your application. Multiple providers will create connection problems.
    </Warning>
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import React from 'react';
    import {
      AmityUiKitSocial,
      AmityUiKitProvider,
    } from 'amity-react-native-social-ui-kit';

    export default function App() {
      const getAuthToken = async () => {
        // Get auth token from your backend
        const response = await fetch('https://yourapi.com/auth/token');
        const { authToken } = await response.json();
        return authToken;
      };
      
      return (
        <AmityUiKitProvider
          apiKey="YOUR_API_KEY"
          apiRegion="us" // eu, us, or sg
          userId="user-123"
          displayName="John Doe"
          getAuthToken={getAuthToken}
          apiEndpoint="https://api.us.amity.co"
        >
          <AmityUiKitSocial />
        </AmityUiKitProvider>
      );
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:amity_uikit_beta_service/amity_uikit_beta_service.dart';

    void login() async {
      try {
        await AmityCoreClient.login(
          'user-123',
          sessionHandler: (AccessTokenRenewal renewal) {
            renewal.renew();
          },
        )
            .displayName('John Doe')
            .authToken('auth-token-from-backend')
            .submit();

        print('Login successful');
      } catch (error) {
        print('Login failed: $error');
      }
    }

    class MyApp extends StatelessWidget {
      @override
      Widget build(BuildContext context) {
        return AmityUIKitProvider(
          child: SocialHomePageConfigProviderWidget(),
        );
      }
    }
    ```
  </Tab>
</Tabs>

***

## User Management

### User ID Guidelines

Your user identification strategy is crucial for a smooth user experience:

<AccordionGroup>
  <Accordion title="Unique Identification">
    **Best Practices:**

    * Use your internal user ID or UUID
    * Ensure IDs are unique across your entire user base
    * Keep IDs consistent across all platforms

    **Avoid:**

    * Email addresses (users might change emails)
    * Phone numbers (users might change numbers)
    * Display names (not unique)
  </Accordion>

  <Accordion title="Character Requirements">
    **Valid Characters:**

    * Alphanumeric characters (a-z, A-Z, 0-9)
    * Underscores (\_) and hyphens (-)
    * Maximum length: 255 characters

    **Invalid Characters:**

    * Spaces or special characters (@, #, \$, etc.)
    * Emojis or unicode characters
  </Accordion>

  <Accordion title="Production Considerations">
    **Security:**

    * Don't expose sensitive information in user IDs
    * Consider hashing user IDs if needed
    * Implement server-side validation

    **Scalability:**

    * Use a consistent ID format
    * Plan for user merging scenarios
    * Consider ID migration strategies
  </Accordion>
</AccordionGroup>

### Session Management

<Steps>
  <Step title="User Login">
    When a user logs into your app, register them with social.plus. The device will be tied to this user.
  </Step>

  <Step title="Session Persistence">
    The SDK automatically maintains sessions across app launches. No additional action needed.
  </Step>

  <Step title="User Logout">
    When users log out, properly unregister the device to prevent unauthorized access:

    <Tabs>
      <Tab title="iOS">
        ```swift theme={null}
        // Unregister device on logout
        AmityUIKitManager.unregisterDevice()
        ```

        <Info>
          Unregistering a device is synchronous. Once called, the SDK disconnects from the server and wipes the user session.
        </Info>
      </Tab>

      <Tab title="Android">
        ```kotlin theme={null}
        AmityCoreClient.logout()
            .submit()
            .subscribe({
                // Successfully logged out
                navigateToLogin()
            }, { error ->
                Log.e("Logout", "Failed", error)
            })
        ```
      </Tab>

      <Tab title="Web/React">
        ```typescript theme={null}
        // For web applications, remove the provider or navigate away
        const handleLogout = () => {
          // Clear user state and navigate to login
          setCurrentUser(null);
          navigate('/login');
        };
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="User Switching">
    To switch users, unregister the current user first, then register the new user:

    ```typescript theme={null}
    // 1. Unregister current user
    await amitySDK.unregisterDevice();

    // 2. Register new user
    await amitySDK.registerDevice(newUserId, newDisplayName);
    ```
  </Step>
</Steps>

***

## Advanced Configuration

### Environment Management

Organize your configuration for different environments:

<Tabs>
  <Tab title="Development">
    ```typescript theme={null}
    const config = {
      apiKey: "dev_b24c28bc...",
      apiRegion: "us",
      debug: true,
      // No auth token needed for development
    };
    ```
  </Tab>

  <Tab title="Production">
    ```typescript theme={null}
    const config = {
      apiKey: process.env.REACT_APP_AMITY_API_KEY,
      apiRegion: process.env.REACT_APP_AMITY_REGION,
      debug: false,
      // Auth token required for production
      getAuthToken: async () => {
        const response = await fetch('/api/auth/social-plus-token');
        const { authToken } = await response.json();
        return authToken;
      }
    };
    ```
  </Tab>
</Tabs>

### Error Handling

Implement comprehensive error handling for authentication:

```typescript theme={null}
const AuthenticationService = {
  async authenticateUser(userId: string, displayName: string, authToken?: string) {
    try {
      if (authToken) {
        // Production mode with auth token
        await amitySDK.registerDevice(userId, displayName, authToken);
      } else {
        // Development mode
        await amitySDK.registerDevice(userId, displayName);
      }
      
      console.log('Authentication successful');
      return { success: true };
    } catch (error) {
      console.error('Authentication failed:', error);
      
      // Handle specific error types
      if (error.code === 'INVALID_API_KEY') {
        return { success: false, error: 'Invalid API credentials' };
      } else if (error.code === 'INVALID_AUTH_TOKEN') {
        return { success: false, error: 'Invalid or expired auth token' };
      } else if (error.code === 'NETWORK_ERROR') {
        return { success: false, error: 'Network connection failed' };
      }
      
      return { success: false, error: 'Authentication failed' };
    }
  },
  
  async logoutUser() {
    try {
      await amitySDK.unregisterDevice();
      return { success: true };
    } catch (error) {
      console.error('Logout failed:', error);
      return { success: false, error: 'Logout failed' };
    }
  }
};
```

***

## Backend Integration

For production applications, you'll need to implement auth token generation on your backend:

<Card title="Backend Auth Token Implementation" icon="server" href="/social-plus-sdk/getting-started/authentication#backend-token-generation">
  Learn how to implement secure auth token generation, token validation, and server-to-server communication with social.plus
</Card>

### Quick Backend Example

Here's a simplified example of auth token generation:

```javascript theme={null}
// Example Node.js backend endpoint
app.post('/api/auth/social-plus-token', authenticateUser, async (req, res) => {
  try {
    // User is already authenticated by your middleware
    const { userId } = req.user;
    
    // Generate auth token for social.plus
    const authToken = await generateSocialPlusAuthToken(userId);
    
    res.json({ authToken });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate auth token' });
  }
});
```

<Warning>
  **Security Note**: Never generate auth tokens on the client side. They must be created by your secure backend after verifying the user's identity.
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Failures">
    **Invalid API Key (401 Error):**

    * Verify API key is correct and not truncated
    * Check that the API key matches your console account
    * Ensure no extra spaces or characters

    **Invalid Auth Token (403 Error):**

    * Verify auth token is properly generated by your backend
    * Check token hasn't expired
    * Ensure token format matches social.plus requirements

    **Region Mismatch:**

    * Verify region matches your console setup
    * Check endpoint URLs are correct
    * Confirm region code format (us/eu/sg)
  </Accordion>

  <Accordion title="Device Registration Issues">
    **Device Already Registered:**

    * Unregister existing user first
    * Wait for previous session to properly close
    * Clear app data if needed (development only)

    **Invalid User ID Format:**

    * Remove special characters and spaces
    * Check user ID length (max 255 characters)
    * Use only alphanumeric characters and underscores

    **Session Conflicts:**

    * Ensure proper logout before switching users
    * Check for multiple provider instances (Web/React)
    * Verify device registration cleanup
  </Accordion>

  <Accordion title="Platform-Specific Issues">
    **iOS:**

    * Ensure registration is called on main thread
    * Check for proper app lifecycle handling
    * Verify push notification setup if using

    **Android:**

    * Implement proper Activity/Fragment lifecycle
    * Check for ProGuard/R8 obfuscation issues
    * Verify session handler implementation

    **Web/React:**

    * Ensure single provider instance at app root
    * Import CSS styles for proper component rendering
    * Check for CORS issues in development

    **React Native:**

    * Verify native module linking
    * Check platform-specific permissions
    * Test on physical devices for push notifications

    **Flutter:**

    * Check session handler implementation
    * Verify platform permissions are configured
    * Ensure proper async/await usage
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that authentication is configured, you can explore social.plus UIKit features:

<CardGroup cols={2}>
  <Card title="Explore Components" icon="puzzle-piece" href="/uikit/components/overview">
    Browse available UI components and features
  </Card>

  <Card title="Customize Appearance" icon="palette" href="/uikit/customization/overview">
    Learn how to customize themes and styling
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Platform Guides" icon="mobile" href="/uikit/platform-guides/ios-specific">
    Platform-specific configuration and optimization
  </Card>

  <Card title="Authentication Deep Dive" icon="shield" href="/social-plus-sdk/getting-started/authentication">
    Complete authentication concepts and backend implementation
  </Card>
</CardGroup>

### User ID Guidelines

Your user identification strategy is crucial for a smooth user experience:

<AccordionGroup>
  <Accordion title="Unique Identification">
    **Best Practices:**

    * Use your internal user ID or UUID
    * Ensure IDs are unique across your entire user base
    * Keep IDs consistent across all platforms

    **Avoid:**

    * Email addresses (users might change emails)
    * Phone numbers (users might change numbers)
    * Display names (not unique)
  </Accordion>

  <Accordion title="Character Requirements">
    **Valid Characters:**

    * Alphanumeric characters (a-z, A-Z, 0-9)
    * Underscores (\_) and hyphens (-)
    * Maximum length: 255 characters

    **Invalid Characters:**

    * Spaces or special characters (@, #, \$, etc.)
    * Emojis or unicode characters
  </Accordion>

  <Accordion title="Production Considerations">
    **Security:**

    * Don't expose sensitive information in user IDs
    * Consider hashing user IDs if needed
    * Implement server-side validation

    **Scalability:**

    * Use a consistent ID format
    * Plan for user merging scenarios
    * Consider ID migration strategies
  </Accordion>
</AccordionGroup>

### Session Management

<Warning>
  **Device Binding**: Once registered, a device is permanently tied to a user ID until explicitly unregistered or inactive for 90+ days. Plan your authentication flow carefully.
</Warning>

<Steps>
  <Step title="User Login">
    When a user logs into your app, register them with social.plus:

    ```typescript theme={null}
    // Register the current device with the user
    await amitySDK.register(userId, displayName);
    ```
  </Step>

  <Step title="Session Persistence">
    The SDK automatically maintains sessions across app launches. No additional action needed.
  </Step>

  <Step title="User Logout">
    When users log out, properly unregister the device:

    <Tabs>
      <Tab title="iOS">
        ```swift theme={null}
        AmitySDK.unregisterDevice { success, error in
            if success {
                // Device unregistered successfully
                self.returnToLoginScreen()
            } else {
                // Handle error
                print("Logout failed: \(error?.localizedDescription ?? "")")
            }
        }
        ```
      </Tab>

      <Tab title="Android">
        ```kotlin theme={null}
        AmityCoreClient.logout()
            .submit()
            .subscribe({
                // Successfully logged out
                navigateToLogin()
            }, { error ->
                Log.e("Logout", "Failed", error)
            })
        ```
      </Tab>

      <Tab title="Web/React">
        ```typescript theme={null}
        // For web applications, simply remove the provider
        // or navigate away from UIKit components
        const handleLogout = () => {
          // Clear user state
          setCurrentUser(null);
          // Navigate to login
          navigate('/login');
        };
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="User Switching">
    To switch users, unregister the current user first, then register the new user:

    ```typescript theme={null}
    // 1. Unregister current user
    await amitySDK.unregisterDevice();

    // 2. Register new user
    await amitySDK.register(newUserId, newDisplayName);
    ```
  </Step>
</Steps>

***

## Advanced Configuration

### Environment Management

Organize your configuration for different environments:

<Tabs>
  <Tab title="Development">
    ```typescript theme={null}
    const config = {
      apiKey: "dev_b24c28bc...",
      apiRegion: "us",
      debug: true,
      enableLogging: true,
      // Optional: Use test endpoints
      apiEndpoint: "https://api.staging.amity.co"
    };
    ```
  </Tab>

  <Tab title="Production">
    ```typescript theme={null}
    const config = {
      apiKey: process.env.REACT_APP_AMITY_API_KEY,
      apiRegion: process.env.REACT_APP_AMITY_REGION,
      debug: false,
      enableLogging: false,
      // Use production endpoints
      apiEndpoint: `https://api.${process.env.REACT_APP_AMITY_REGION}.amity.co`
    };
    ```
  </Tab>

  <Tab title="Enterprise">
    ```typescript theme={null}
    // For enterprise customers with custom domains
    const config = {
      apiKey: "your_enterprise_api_key",
      apiEndpoint: "https://api.your-company.com",
      // Additional enterprise features
      enableCustomBranding: true,
      enableAdvancedModeration: true
    };
    ```
  </Tab>
</Tabs>

### Error Handling

Implement comprehensive error handling for authentication:

```typescript theme={null}
const AuthenticationService = {
  async authenticateUser(userId: string, displayName: string) {
    try {
      await amitySDK.register(userId, displayName);
      console.log('Authentication successful');
      return { success: true };
    } catch (error) {
      console.error('Authentication failed:', error);
      
      // Handle specific error types
      if (error.code === 'INVALID_API_KEY') {
        return { success: false, error: 'Invalid API credentials' };
      } else if (error.code === 'NETWORK_ERROR') {
        return { success: false, error: 'Network connection failed' };
      } else if (error.code === 'INVALID_USER_ID') {
        return { success: false, error: 'Invalid user ID format' };
      }
      
      return { success: false, error: 'Authentication failed' };
    }
  },
  
  async logoutUser() {
    try {
      await amitySDK.unregisterDevice();
      return { success: true };
    } catch (error) {
      console.error('Logout failed:', error);
      return { success: false, error: 'Logout failed' };
    }
  }
};
```

### Security Best Practices

<AccordionGroup>
  <Accordion title="API Key Security">
    **Client-Side Applications:**

    * Store API keys in environment variables
    * Never commit API keys to version control
    * Use different keys for development and production

    **Server-Side Authentication (Recommended):**

    * Implement server-side token generation
    * Use short-lived authentication tokens
    * Validate users on your backend before issuing tokens
  </Accordion>

  <Accordion title="User Validation">
    **Input Validation:**

    * Validate user IDs before registration
    * Sanitize display names
    * Implement rate limiting for authentication attempts

    **Session Security:**

    * Monitor for unusual authentication patterns
    * Implement proper logout flows
    * Consider implementing session timeouts
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Failures">
    **Invalid API Key (401 Error):**

    * Verify API key is correct and not truncated
    * Check that the API key matches your console account
    * Ensure no extra spaces or characters

    **Region Mismatch (403 Error):**

    * Verify region matches your console setup
    * Check endpoint URLs are correct
    * Confirm region code format (us/eu/sg)

    **Network Issues:**

    * Test internet connectivity
    * Check firewall/proxy settings
    * Verify DNS resolution for amity.co domains
  </Accordion>

  <Accordion title="User Registration Issues">
    **Invalid User ID Format:**

    * Remove special characters and spaces
    * Check user ID length (max 255 characters)
    * Use only alphanumeric characters and underscores

    **Device Already Registered:**

    * Unregister existing user first
    * Wait for previous session to properly close
    * Clear app data if needed (development only)

    **Display Name Issues:**

    * Ensure display name is not empty
    * Check for special character restrictions
    * Verify UTF-8 encoding for international names
  </Accordion>

  <Accordion title="Platform-Specific Issues">
    **iOS:**

    * Ensure setup is called on main thread
    * Check for proper delegate implementations
    * Verify bundle identifier permissions

    **Android:**

    * Implement proper Activity/Fragment lifecycle
    * Check for ProGuard/R8 obfuscation issues
    * Verify network permissions in manifest

    **Web/React:**

    * Ensure provider wraps all UIKit components
    * Check for CORS issues in development
    * Verify React version compatibility

    **React Native:**

    * Check platform-specific permissions
    * Verify native module linking
    * Test on physical devices, not just simulators

    **Flutter:**

    * Check pubspec.yaml dependencies
    * Verify platform permissions are configured
    * Test hot reload vs full restart
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that authentication is configured, you can explore social.plus UIKit features:

<CardGroup cols={2}>
  <Card title="Explore Components" icon="puzzle-piece" href="/uikit/components/overview">
    Browse available UI components and features
  </Card>

  <Card title="Customize Appearance" icon="palette" href="/uikit/customization/overview">
    Learn how to customize themes and styling
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Platform Guides" icon="mobile" href="/uikit/platform-guides/ios-specific">
    Platform-specific configuration and optimization
  </Card>

  <Card title="View Examples" icon="code" href="/uikit/examples/overview">
    See real-world implementation examples
  </Card>
</CardGroup>

<Steps>
  <Step title="Initialize SDK">
    Initialize the SDK in your `Application` class or main activity:

    ```kotlin theme={null}
    import com.amity.socialcloud.sdk.AmityCoreClient
    import com.amity.socialcloud.uikit.AmityUIKit

    // In Application class or MainActivity
    AmityCoreClient.setup(
        apiKey = "YOUR_API_KEY",
        region = AmityRegionalEndpoint.US // or EU, SG
    )
    ```
  </Step>

  <Step title="Register User">
    Register and authenticate the user:

    ```kotlin theme={null}
    AmityCoreClient.login("unique_user_id")
        .displayName("User Display Name")
        .build()
        .submit()
        .observeOn(AndroidSchedulers.mainThread())
        .subscribe({ user ->
            // User registered successfully
            Log.d("Auth", "User registered: ${user.displayName}")
        }, { error ->
            // Handle registration error
            Log.e("Auth", "Registration failed", error)
        })
    ```
  </Step>

  <Step title="Launch UIKit">
    Start social.plus UIKit activities:

    ```kotlin theme={null}
    import com.amity.socialcloud.uikit.AmityUIKit

    // Launch social features
    AmityUIKit.openSocialHome(this)

    // Or launch specific features
    AmityUIKit.openChatHome(this)
    ```
  </Step>
</Steps>

### Web/React Setup

<Steps>
  <Step title="Initialize Provider">
    Set up the `AmityUiKitProvider` in your React app:

    ```typescript theme={null}
    import React from 'react';
    import { AmityUiKitProvider } from '@amityco/ui-kit';

    function App() {
      return (
        <AmityUiKitProvider
          apiKey="YOUR_API_KEY"
          apiRegion="US" // or "EU", "SG"
          userId="unique_user_id"
          displayName="User Display Name"
        >
          {/* Your app content */}
        </AmityUiKitProvider>
      );
    }
    ```
  </Step>

  <Step title="Use Components">
    Import and use social.plus components:

    ```typescript theme={null}
    import { AmityUiKitSocial } from '@amityco/ui-kit';

    function SocialPage() {
      return (
        <div className="social-container">
          <AmityUiKitSocial />
        </div>
      );
    }
    ```
  </Step>
</Steps>

### React Native Setup

<Steps>
  <Step title="Initialize Provider">
    Wrap your app with the provider:

    ```typescript theme={null}
    import React from 'react';
    import {
      AmityUiKitProvider,
      AmityUiKitSocial,
    } from 'amity-react-native-social-ui-kit';

    export default function App() {
      return (
        <AmityUiKitProvider
          apiKey="YOUR_API_KEY"
          apiRegion="US" // or "EU", "SG"
          userId="unique_user_id"
          displayName="User Display Name"
        >
          <AmityUiKitSocial />
        </AmityUiKitProvider>
      );
    }
    ```
  </Step>
</Steps>

### Flutter Setup

<Steps>
  <Step title="Initialize App">
    Set up the `AmityApp` widget:

    ```dart theme={null}
    import 'package:amity_uikit_beta_service/amity_uikit_beta_service.dart';

    class MyApp extends StatelessWidget {
      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          home: AmityApp(
            apiKey: 'YOUR_API_KEY',
            apiRegion: 'US', // or 'EU', 'SG'
            userId: 'unique_user_id',
            displayName: 'User Display Name',
            child: AmitySocialHomePage(),
          ),
        );
      }
    }
    ```
  </Step>
</Steps>

***

## Authentication Best Practices

### User ID Guidelines

<AccordionGroup>
  <Accordion title="Unique Identification">
    * Use a unique, persistent identifier for each user
    * Avoid using email addresses or phone numbers directly
    * Consider using UUIDs or your system's internal user IDs
  </Accordion>

  <Accordion title="Consistency">
    * Maintain the same user ID across app sessions
    * Ensure user IDs remain consistent across different platforms
    * Don't change user IDs after initial registration
  </Accordion>

  <Accordion title="Security">
    * Never expose sensitive user information in user IDs
    * Use a hash or encoded value if needed
    * Implement proper server-side validation
  </Accordion>
</AccordionGroup>

### Session Management

<Warning>
  **Device Binding**: A device registered with a specific `userId` will be permanently tied to that user until you deliberately unregister the device, or until the device has been inactive for more than 90 days.
</Warning>

<Steps>
  <Step title="Registration">
    Register the device with the user ID when the user logs in to your app.
  </Step>

  <Step title="Session Persistence">
    The SDK automatically maintains the session across app launches.
  </Step>

  <Step title="Logout">
    Properly unregister the device when the user logs out:

    <Tabs>
      <Tab title="iOS">
        ```swift theme={null}
        AmitySDK.unregisterDevice { success, error in
            if success {
                print("Device unregistered successfully")
            }
        }
        ```
      </Tab>

      <Tab title="Android">
        ```kotlin theme={null}
        AmityCoreClient.logout()
            .submit()
            .subscribe({
                // Device unregistered successfully
            }, { error ->
                // Handle logout error
            })
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## Configuration Options

### Optional Parameters

<AccordionGroup>
  <Accordion title="Custom Endpoints">
    For enterprise customers with custom endpoints:

    ```typescript theme={null}
    // Web/React
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiEndpoint="https://api.custom-domain.com"
      // ... other props
    />
    ```
  </Accordion>

  <Accordion title="Authentication Tokens">
    For server-side authentication (recommended for production):

    ```typescript theme={null}
    // Use secure token instead of API key
    <AmityUiKitProvider
      authToken="secure_server_generated_token"
      // ... other props
    />
    ```
  </Accordion>
</AccordionGroup>

### Environment Configuration

<Tabs>
  <Tab title="Development">
    ```typescript theme={null}
    const config = {
      apiKey: "dev_api_key",
      apiRegion: "US",
      debug: true,
      logging: true
    };
    ```
  </Tab>

  <Tab title="Production">
    ```typescript theme={null}
    const config = {
      apiKey: process.env.REACT_APP_AMITY_API_KEY,
      apiRegion: process.env.REACT_APP_AMITY_REGION,
      debug: false,
      logging: false
    };
    ```
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Errors">
    **Invalid API Key**: Verify your API key is correct and matches your console account.

    **Wrong Region**: Ensure the region matches where your social.plus application was created.

    **Network Issues**: Check internet connectivity and firewall settings.
  </Accordion>

  <Accordion title="User Registration Issues">
    **Duplicate User**: User IDs must be unique within your application.

    **Invalid Characters**: User IDs should only contain alphanumeric characters and underscores.

    **Session Conflicts**: Ensure proper logout before registering a different user.
  </Accordion>

  <Accordion title="Platform-Specific Issues">
    **iOS**: Check that you're calling setup methods on the main thread.

    **Android**: Ensure proper lifecycle management in activities/fragments.

    **Web**: Verify the provider wraps all components that need social.plus context.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Components" icon="puzzle-piece" href="/uikit/components/overview">
    Browse available UI components and features
  </Card>

  <Card title="Customize Appearance" icon="palette" href="/uikit/customization/overview">
    Learn how to customize themes and styling
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="View Examples" icon="code" href="/uikit/examples/overview">
    See real-world implementation examples
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore the complete API documentation
  </Card>
</CardGroup>