Accessing the API

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 your Package.swift file:

dependencies: [
    .package(url: "https://github.com/arpwal/contactsmanager-ios.git", from: "<latest-version>")
]

Or in Xcode:

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: "[email protected]",
    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: '[email protected]', // 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.framework from 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 = @"[email protected]";  // 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’s build.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 your AndroidManifest.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 = "[email protected]", // 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 the ContactsService 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: '[email protected]'
    }
  });
} 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

This approach ensures that only authenticated devices with valid server-issued tokens can access your users’ contact data. Your server maintains complete control over data access, allowing you to:

Authenticate users through your existing auth system
Immediately revoke access when needed
Protect against unauthorized data access
Monitor and audit access patterns

See the server setup section in the Quickstart guide for implementation details.

Get Started

Features

Services

Webhooks

Models

Installation

Swift Package Manager

SDK Initialization

Installation

Platform Setup

iOS Setup

Android Setup

SDK Initialization

Installation

SDK Initialization

Installation

Get Latest Version

Required Permissions

SDK Initialization

Accessing the Service

Error Handling

Get Started

Features

Services

Webhooks

Models

​Installation

​Swift Package Manager

​SDK Initialization

​Installation

​Platform Setup

iOS Setup

Android Setup

​SDK Initialization

​Installation

​SDK Initialization

​Installation

​Get Latest Version

​Required Permissions

​SDK Initialization

​Accessing the Service

​Error Handling

Installation

Swift Package Manager

SDK Initialization

Installation

Platform Setup

SDK Initialization

Installation

SDK Initialization

Installation

Get Latest Version

Required Permissions

SDK Initialization

Accessing the Service

Error Handling