New to social.plus Authentication? For comprehensive authentication concepts, security patterns, and backend implementation, see the SDK Authentication Guide. This guide focuses specifically on UIKit implementation.
Prerequisites
Before setting up authentication, ensure you have:API Credentials
Your API key and region from social.plus Console
UIKit Installed
social.plus UIKit installed in your project
Coming from First Steps? If you followed the First Steps guide, you’ve already completed basic authentication. This guide provides comprehensive details and production-ready patterns.
Get Your API Credentials
Access social.plus Console
Visit Console
Go to social.plus Console and sign in to your account.
Regional Configuration
social.plus operates in multiple regions for optimal performance and compliance:- United States
- Europe
- Singapore
Authentication Modes
social.plus UIKit supports two authentication modes depending on your security requirements:- Development Mode
- Production Mode
Quick Setup (API Key Only)Perfect for development, testing, and proof-of-concept applications:
Development mode is great for getting started quickly, but should not be used in production applications.
Learn About Auth Tokens
Understanding auth tokens, server-to-server verification, and backend implementation patterns
Device Registration
Understanding Device Binding
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:- iOS
- Android
- Web/React
- React Native
- Flutter
Push Notifications: social.plus UIKit doesn’t manage push permission requests or token creation. Your app must handle these and pass the device token.
User Management
User ID Guidelines
Your user identification strategy is crucial for a smooth user experience:Unique Identification
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
- Email addresses (users might change emails)
- Phone numbers (users might change numbers)
- Display names (not unique)
Character Requirements
Character Requirements
Valid Characters:
- Alphanumeric characters (a-z, A-Z, 0-9)
- Underscores (_) and hyphens (-)
- Maximum length: 255 characters
- Spaces or special characters (@, #, $, etc.)
- Emojis or unicode characters
Production Considerations
Production Considerations
Security:
- Don’t expose sensitive information in user IDs
- Consider hashing user IDs if needed
- Implement server-side validation
- Use a consistent ID format
- Plan for user merging scenarios
- Consider ID migration strategies
Session Management
User Login
When a user logs into your app, register them with social.plus. The device will be tied to this user.
Session Persistence
The SDK automatically maintains sessions across app launches. No additional action needed.
User Logout
When users log out, properly unregister the device to prevent unauthorized access:
- iOS
- Android
- Web/React
Unregistering a device is synchronous. Once called, the SDK disconnects from the server and wipes the user session.
Advanced Configuration
Environment Management
Organize your configuration for different environments:- Development
- Production
Error Handling
Implement comprehensive error handling for authentication:Backend Integration
For production applications, you’ll need to implement auth token generation on your backend:Backend Auth Token Implementation
Learn how to implement secure auth token generation, token validation, and server-to-server communication with social.plus
Quick Backend Example
Here’s a simplified example of auth token generation:Troubleshooting
Authentication Failures
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
- Verify auth token is properly generated by your backend
- Check token hasn’t expired
- Ensure token format matches social.plus requirements
- Verify region matches your console setup
- Check endpoint URLs are correct
- Confirm region code format (us/eu/sg)
Device Registration Issues
Device Registration Issues
Device Already Registered:
- Unregister existing user first
- Wait for previous session to properly close
- Clear app data if needed (development only)
- Remove special characters and spaces
- Check user ID length (max 255 characters)
- Use only alphanumeric characters and underscores
- Ensure proper logout before switching users
- Check for multiple provider instances (Web/React)
- Verify device registration cleanup
Platform-Specific Issues
Platform-Specific Issues
iOS:
- Ensure registration is called on main thread
- Check for proper app lifecycle handling
- Verify push notification setup if using
- Implement proper Activity/Fragment lifecycle
- Check for ProGuard/R8 obfuscation issues
- Verify session handler implementation
- Ensure single provider instance at app root
- Import CSS styles for proper component rendering
- Check for CORS issues in development
- Verify native module linking
- Check platform-specific permissions
- Test on physical devices for push notifications
- Check session handler implementation
- Verify platform permissions are configured
- Ensure proper async/await usage
Next Steps
Now that authentication is configured, you can explore social.plus UIKit features:Explore Components
Browse available UI components and features
Customize Appearance
Learn how to customize themes and styling
Platform Guides
Platform-specific configuration and optimization
Authentication Deep Dive
Complete authentication concepts and backend implementation
User ID Guidelines
Your user identification strategy is crucial for a smooth user experience:Unique Identification
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
- Email addresses (users might change emails)
- Phone numbers (users might change numbers)
- Display names (not unique)
Character Requirements
Character Requirements
Valid Characters:
- Alphanumeric characters (a-z, A-Z, 0-9)
- Underscores (_) and hyphens (-)
- Maximum length: 255 characters
- Spaces or special characters (@, #, $, etc.)
- Emojis or unicode characters
Production Considerations
Production Considerations
Security:
- Don’t expose sensitive information in user IDs
- Consider hashing user IDs if needed
- Implement server-side validation
- Use a consistent ID format
- Plan for user merging scenarios
- Consider ID migration strategies
Session Management
Session Persistence
The SDK automatically maintains sessions across app launches. No additional action needed.
Advanced Configuration
Environment Management
Organize your configuration for different environments:- Development
- Production
- Enterprise
Error Handling
Implement comprehensive error handling for authentication:Security Best Practices
API Key Security
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
- Implement server-side token generation
- Use short-lived authentication tokens
- Validate users on your backend before issuing tokens
User Validation
User Validation
Input Validation:
- Validate user IDs before registration
- Sanitize display names
- Implement rate limiting for authentication attempts
- Monitor for unusual authentication patterns
- Implement proper logout flows
- Consider implementing session timeouts
Troubleshooting
Authentication Failures
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
- Verify region matches your console setup
- Check endpoint URLs are correct
- Confirm region code format (us/eu/sg)
- Test internet connectivity
- Check firewall/proxy settings
- Verify DNS resolution for amity.co domains
User Registration Issues
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
- Unregister existing user first
- Wait for previous session to properly close
- Clear app data if needed (development only)
- Ensure display name is not empty
- Check for special character restrictions
- Verify UTF-8 encoding for international names
Platform-Specific Issues
Platform-Specific Issues
iOS:
- Ensure setup is called on main thread
- Check for proper delegate implementations
- Verify bundle identifier permissions
- Implement proper Activity/Fragment lifecycle
- Check for ProGuard/R8 obfuscation issues
- Verify network permissions in manifest
- Ensure provider wraps all UIKit components
- Check for CORS issues in development
- Verify React version compatibility
- Check platform-specific permissions
- Verify native module linking
- Test on physical devices, not just simulators
- Check pubspec.yaml dependencies
- Verify platform permissions are configured
- Test hot reload vs full restart
Next Steps
Now that authentication is configured, you can explore social.plus UIKit features:Explore Components
Browse available UI components and features
Customize Appearance
Learn how to customize themes and styling
Platform Guides
Platform-specific configuration and optimization
View Examples
See real-world implementation examples
Web/React Setup
React Native Setup
Flutter Setup
Authentication Best Practices
User ID Guidelines
Unique Identification
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
Consistency
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
Security
Security
- Never expose sensitive user information in user IDs
- Use a hash or encoded value if needed
- Implement proper server-side validation
Session Management
Configuration Options
Optional Parameters
Custom Endpoints
Custom Endpoints
For enterprise customers with custom endpoints:
Authentication Tokens
Authentication Tokens
For server-side authentication (recommended for production):
Environment Configuration
- Development
- Production
Troubleshooting
Authentication Errors
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.
User Registration Issues
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.
Platform-Specific Issues
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.