Documentation Index
Fetch the complete documentation index at: https://docs.contactsmanager.io/llms.txt
Use this file to discover all available pages before exploring further.
Installation
Install and initialize the ContactsManager SDK in your client application.- Swift
- React Native
- Objective-C
- Kotlin
Swift Package Manager
Add the ContactsManager package to your Swift project by adding it as a dependency in yourPackage.swift file:dependencies: [
.package(url: "https://github.com/arpwal/contactsmanager-ios.git", from: "<latest-version>")
]
- Go to File > Swift Packages > Add Package Dependency
- Enter the repository URL:
https://github.com/arpwal/contactsmanager-ios.git - Specify a minimum version of
<latest-version>from the repository - Click Next and complete the integration
SDK Initialization
import ContactsManager
// Create user information
let userInfo = UserInfo(
userId: "user-123",
email: "user@example.com",
phone: "+15555555555",
fullName: "John Doe",
avatarUrl: "https://...", // Optional
metadata: ["key": "value"] // Optional
)
// Initialize the SDK
try await ContactsService.shared.initialize(
withAPIKey: "your-api-key",
token: "user-auth-token", // Optional but recommended for security
userInfo: userInfo
)
// Enable background sync if needed
ContactsService.shared.enableBackgroundSync()
Installation
npm install @contactsmanager/rn
# or
yarn add @contactsmanager/rn
Platform Setup
iOS Setup
- Install CocoaPods dependencies:
cd ios && pod install && cd ..
- Add permissions to
Info.plist:
<key>NSContactsUsageDescription</key>
<string>We need access to your contacts to enable social features</string>
Android Setup
The dependency is automatically added to your project.SDK Initialization
import { initialize, isInitialized, enableBackgroundSync } from '@contactsmanager/rn';
// Check if already initialized
const alreadyInitialized = await isInitialized();
// Initialize with your API key and token from server
const result = await initialize({
apiKey: 'your-api-key',
token: 'user-auth-token', // Optional but recommended for security
userInfo: {
userId: 'unique-user-id',
email: 'user@example.com', // Optional
phone: '+15551234567', // Optional
fullName: 'User Name', // Optional
avatarUrl: 'https://...', // Optional
metadata: { key: 'value' } // Optional
}
});
// Enable background sync if needed
await enableBackgroundSync();
Installation
- Download the latest
ContactsManager.frameworkfrom Releases - Drag and drop the framework into your Xcode project
- Add framework to “Link Binary With Libraries” in Build Phases
- Add to Info.plist:
<key>NSContactsUsageDescription</key>
<string>We need access to contacts to enable social features.</string>
SDK Initialization
#import <ContactsManager/ContactsManager.h>
// Create user info
CMUserInfo *userInfo = [[CMUserInfo alloc] init];
userInfo.userId = @"user123";
userInfo.email = @"user@example.com"; // Optional
userInfo.phone = @"+1234567890"; // Optional
userInfo.fullName = @"John Doe"; // Optional
userInfo.avatarUrl = @"https://..."; // Optional
userInfo.metadata = @{@"key": @"value"}; // Optional
// Initialize with options (optional)
CMContactsManagerOptions *options = [CMContactsManagerOptions defaultOptions];
options.restrictedKeysToFetch = @[@(CMContactDataRestrictionNotes)]; // Optional
// Initialize the service
[[CMContactService sharedInstance] initializeWithAPIKey:@"your_api_key"
token:@"your_token" // Optional
userInfo:userInfo
options:options // Optional
completion:^(BOOL success, NSError * _Nullable error) {
if (success) {
NSLog(@"ContactsManager initialized successfully");
} else {
NSLog(@"Initialization failed: %@", error.localizedDescription);
}
}];
Installation
Add the library to your project’sbuild.gradle:implementation("io.contactsmanager:contactsmanager:1.0.5")
Get Latest Version
You can check for the latest version of the SDK on Maven Central.Required Permissions
Add the following permissions to yourAndroidManifest.xml:<!-- Required for accessing contacts -->
<uses-permission android:name="android.permission.READ_CONTACTS" />
<!-- Required for network operations -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
SDK Initialization
// Initialize the library
private val contactService by lazy { ContactService.getInstance(context) }
// Create user info
val userInfo = UserInfo(
userId = "user-123",
displayName = "John Doe",
email = "user@example.com", // Optional
phone = "+1234567890", // Optional
avatarUrl = "https://...", // Optional
metadata = mapOf("key" to "value") // Optional
)
// Create options
val options = CMContactsManagerOptions.defaultOptions().apply {
// Configure any custom options here if needed
}
// Initialize the service
val initResult = contactService.initialize(
apiKey = API_KEY,
token = "user-auth-token", // Optional but recommended for security
userInfo = userInfo,
options = options // Optional
)
if (initResult.isSuccess) {
// Service initialized successfully
val contacts = initResult.data
} else {
// Handle initialization error
val error = initResult.error
}
Accessing the Service
The ContactsManager SDK provides a comprehensive API through theContactsService class. Here’s how to access and use the service:
- Swift
- React Native
- Objective-C
- Kotlin
// Access the shared instance
let service = ContactsService.shared
// Check initialization status
let isInitialized = service.isInitialized
// Get current state
let state = service.currentState
import {
ContactsService,
isInitialized,
currentState
} from '@contactsmanager/rn';
// Check initialization
const initialized = await isInitialized();
// Get current state
const state = await currentState();
// Access shared instance
CMContactService *service = [CMContactService sharedInstance];
// Check initialization
BOOL isInitialized = service.isInitialized;
// Get current state
CMServiceState state = service.currentState;
// Access service instance
val service = ContactService.getInstance(context)
// Check initialization
val isInitialized = service.isInitialized
// Get current state
val state = service.currentState
Error Handling
The SDK provides comprehensive error handling across all platforms:- Swift
- React Native
- Objective-C
- Kotlin
do {
try await ContactsService.shared.initialize(
withAPIKey: "your-api-key",
token: "user-auth-token",
userInfo: userInfo
)
} catch let error as ContactsServiceError {
switch error {
case .invalidAPIKey:
print("Invalid API key")
case .apiKeyValidationFailed(let reason):
print("API key validation failed: \(reason)")
case .networkError(let error):
print("Network error: \(error.localizedDescription)")
case .initializationFailed(let error):
print("Initialization failed: \(error.localizedDescription)")
case .databaseError(let error):
print("Database error: \(error.localizedDescription)")
case .notInitialized:
print("SDK not initialized")
case .contactsAccessDenied:
print("Contacts access denied")
case .userNotAuthenticated:
print("User not authenticated")
case .invalidUserInfo(let reason):
print("Invalid user info: \(reason)")
case .customError(let message):
print("Error: \(message)")
}
}
try {
await initialize({
apiKey: 'your-api-key',
token: 'user-auth-token',
userInfo: {
userId: 'unique-user-id',
email: 'user@example.com'
}
});
} catch (error) {
switch (error.code) {
case 'INVALID_API_KEY':
console.error('Invalid API key');
break;
case 'API_KEY_VALIDATION_FAILED':
console.error(`API key validation failed: ${error.message}`);
break;
case 'NETWORK_ERROR':
console.error(`Network error: ${error.message}`);
break;
case 'INITIALIZATION_FAILED':
console.error(`Initialization failed: ${error.message}`);
break;
case 'DATABASE_ERROR':
console.error(`Database error: ${error.message}`);
break;
case 'NOT_INITIALIZED':
console.error('SDK not initialized');
break;
case 'CONTACTS_ACCESS_DENIED':
console.error('Contacts access denied');
break;
case 'USER_NOT_AUTHENTICATED':
console.error('User not authenticated');
break;
case 'INVALID_USER_INFO':
console.error(`Invalid user info: ${error.message}`);
break;
default:
console.error(`Unexpected error: ${error.message}`);
}
}
[[CMContactService sharedInstance] initializeWithAPIKey:@"your_api_key"
token:@"your_token"
userInfo:userInfo
options:options
completion:^(BOOL success, NSError * _Nullable error) {
if (!success) {
switch (error.code) {
case CMErrorInvalidAPIKey:
NSLog(@"Invalid API key");
break;
case CMErrorAPIKeyValidationFailed:
NSLog(@"API key validation failed: %@", error.localizedDescription);
break;
case CMErrorNetworkError:
NSLog(@"Network error: %@", error.localizedDescription);
break;
case CMErrorInitializationFailed:
NSLog(@"Initialization failed: %@", error.localizedDescription);
break;
case CMErrorDatabaseError:
NSLog(@"Database error: %@", error.localizedDescription);
break;
case CMErrorNotInitialized:
NSLog(@"SDK not initialized");
break;
case CMErrorContactsAccessDenied:
NSLog(@"Contacts access denied");
break;
case CMErrorUserNotAuthenticated:
NSLog(@"User not authenticated");
break;
case CMErrorInvalidUserInfo:
NSLog(@"Invalid user info: %@", error.localizedDescription);
break;
default:
NSLog(@"Unexpected error: %@", error.localizedDescription);
}
}
}];
try {
val result = contactService.initialize(
apiKey = API_KEY,
token = "user-auth-token",
userInfo = userInfo
)
if (!result.isSuccess) {
when (result.error) {
is ContactsError.InvalidAPIKey ->
Log.e(TAG, "Invalid API key")
is ContactsError.APIKeyValidationFailed ->
Log.e(TAG, "API key validation failed: ${result.error.reason}")
is ContactsError.NetworkError ->
Log.e(TAG, "Network error: ${result.error.message}")
is ContactsError.InitializationFailed ->
Log.e(TAG, "Initialization failed: ${result.error.message}")
is ContactsError.DatabaseError ->
Log.e(TAG, "Database error: ${result.error.message}")
is ContactsError.NotInitialized ->
Log.e(TAG, "SDK not initialized")
is ContactsError.ContactsAccessDenied ->
Log.e(TAG, "Contacts access denied")
is ContactsError.UserNotAuthenticated ->
Log.e(TAG, "User not authenticated")
is ContactsError.InvalidUserInfo ->
Log.e(TAG, "Invalid user info: ${result.error.reason}")
else ->
Log.e(TAG, "Unexpected error: ${result.error}")
}
}
} catch (e: Exception) {
Log.e(TAG, "Unexpected error: ${e.message}")
}
Important: Secure Your Users’ DataServer-side token generation is required to ensure the security of your users’ contact data. By handling authentication through your server, you establish a two-factor security model:
- API Key verification
- Server-generated token validation
- Authenticate users through your existing auth system
- Immediately revoke access when needed
- Protect against unauthorized data access
- Monitor and audit access patterns