Quickstart - Contacts Manager

Installation

ContactsManager offers two installation approaches. For production applications, we strongly recommend the Full Installation approach with server-side token generation.

1. Fast Installation (Client Only)

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>")
]

SDK Initialization (Development Only)

import ContactsManager

// Create user information
let userInfo = UserInfo(
    userId: "user123",
    fullName: "John Doe",
    email: "john@example.com",
    phone: "+1234567890"
)

// Initialize with API key and user info (NOT RECOMMENDED for production)
try await ContactsService.shared.initialize(
    withAPIKey: "your-api-key",
    token: nil, // Will generate token client-side with security warning
    userInfo: userInfo,
    options: ContactsManagerOptions(
        verboseLogging: true,
        autoSyncEnabled: true
    )
)

Installation

npm install @contactsmanager/rn
# or
yarn add @contactsmanager/rn

SDK Initialization (Development Only)

import { initialize, isInitialized } from '@contactsmanager/rn';

// Create user information
const userInfo = {
  userId: "user123",
  fullName: "John Doe",
  email: "john@example.com",
  phone: "+1234567890"
};

// Check if already initialized
const alreadyInitialized = await isInitialized();

// Initialize with API key and user info (NOT RECOMMENDED for production)
const result = await initialize("your-api-key", userInfo, null, {
  verboseLogging: true,
  autoSyncEnabled: true
});

SDK Initialization (Development Only)

#import <ContactsManager/ContactsManager.h>

// Create user info
CMUserInfo *userInfo = [[CMUserInfo alloc] init];
userInfo.userId = @"user123";
userInfo.email = @"user@example.com";
userInfo.phone = @"+1234567890";
userInfo.fullName = @"John Doe";

// Initialize with options
CMContactsManagerOptions *options = [CMContactsManagerOptions defaultOptions];
options.verboseLogging = YES;
options.autoSyncEnabled = YES;

// Initialize the service (NOT RECOMMENDED for production)
[[CMContactService sharedInstance] initializeWithAPIKey:@"your_api_key"
                                                  token:nil // Will generate client-side
                                               userInfo:userInfo
                                                options:options
                                             completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        NSLog(@"ContactsManager initialized successfully");
    } else {
        NSLog(@"Initialization failed: %@", error.localizedDescription);
    }
}];

SDK Initialization (Development Only)

// Initialize the library
private val contactService by lazy { ContactService.getInstance(context) }

// Create user info
val userInfo = UserInfo(
    userId = "user-123",
    displayName = "John Doe",
    email = "john@example.com",
    phone = "+1234567890"
)

// Create options
val options = CMContactsManagerOptions.defaultOptions().apply {
    verboseLogging = true
    autoSyncEnabled = true
}

// Initialize the service (NOT RECOMMENDED for production)
val initResult = contactService.initialize(
    apiKey = "your-api-key",
    userInfo = userInfo,
    options = options
)

if (initResult.isSuccess) {
    // Service initialized successfully
    val contacts = initResult.data
} else {
    // Handle initialization error
    val error = initResult.error
}

2. Full Installation (Recommended)

This is the secure, production-ready approach that sets up your server first to manage user creation and token generation.

Step A: Server Setup

Set up your backend to create users and generate authentication tokens for the ContactsManager SDK.

Python
Node.js

Installation

pip install contactsmanager

The Python SDK is open source and available on GitHub: github.com/arpwal/contactsmanager-py

Create User (First Time Setup)

from contactsmanager import ContactsManagerClient, UserInfo, DeviceInfo

# Initialize the client
client = ContactsManagerClient(
    api_key="your-api-key",
    api_secret="your-api-secret", 
    org_id="your-org-id"
)

# Create user info
user_info = UserInfo(
    user_id="user-123",
    full_name="John Doe",
    email="john@example.com",  # Optional but recommended
    phone="+1234567890",       # Optional but recommended
    avatar_url="https://...",  # Optional
    metadata={"key": "value"}  # Optional
)

# Create device info (optional)
device_info = DeviceInfo(
    device_name="iPhone 15",
    os_version="iOS 17.5",
    app_version="1.0.0"
)

# Create/update user and get token (first time or when user data changes)
response = client.create_user(
    user_info=user_info,
    device_info=device_info,
    expiry_seconds=86400  # 24 hours
)

# Use the token for client SDK initialization
token = response.token
user_data = response.user  # Created/updated user information

Generate Token (Subsequent Logins)

# For subsequent logins, generate a new token for existing users
token_data = client.generate_token(
    user_id="user-123",
    device_info={"device_name": "iPhone 15", "os_version": "iOS 17.5"},
    expiration_seconds=86400  # 24 hours
)

# The token to be used in client SDK initialization
token = token_data["token"]

Installation

npm install @contactsmanager/server

The Node.js SDK is open source and available on GitHub: github.com/arpwal/contactsmanager-nodejsFull documentation for the Node.js SDK is also available on npm.

Create User (First Time Setup)

import { ContactsManagerClient } from '@contactsmanager/server';

// Initialize the client
const client = new ContactsManagerClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  orgId: 'your-org-id'
});

// Create/update user and get token (first time or when user data changes)
async function createUserAndGetToken() {
  const userInfo = {
    userId: 'user-123',
    fullName: 'John Doe',
    email: 'john@example.com',      // Optional but recommended
    phone: '+1234567890',           // Optional but recommended
    avatarUrl: 'https://...',       // Optional
    metadata: { key: 'value' }      // Optional
  };

  const deviceInfo = {
    deviceName: 'iPhone 15',
    osVersion: 'iOS 17.5',
    appVersion: '1.0.0'
  };

  const response = await client.createUser(
    userInfo,
    deviceInfo,
    86400  // 24 hours expiry
  );

  // Use the token for client SDK initialization
  const token = response.token;
  const userData = response.user;  // Created/updated user information
  
  return { token, userData };
}

Generate Token (Subsequent Logins)

// For subsequent logins, generate a new token for existing users
async function generateUserToken() {
  const tokenData = await client.generateToken({
    userId: 'user-123',
    deviceInfo: { deviceName: 'iPhone 15', osVersion: 'iOS 17.5' },
    expirationSeconds: 86400 // 24 hours
  });
  
  // The token to be used in client SDK initialization
  const token = tokenData.token;
  return token;
}

Step B: Client Setup

Install and initialize the ContactsManager SDK in your client application using the token from your server.

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 (Recommended)

import ContactsManager

// Initialize the SDK with server-generated token (RECOMMENDED)
try await ContactsService.shared.initialize(
    withToken: "server-generated-token",
    options: ContactsManagerOptions(
        verboseLogging: false,
        autoSyncEnabled: true
    )
)

This is the recommended approach: The token should be generated by your server using the steps above. The SDK will automatically fetch user information from the server using the token, ensuring data consistency and security.

Installation

npm install @contactsmanager/rn
# or
yarn add @contactsmanager/rn

Expo Setup

If you’re using Expo, you’ll need to generate native dependencies before proceeding with platform setup:

npx expo prebuild

This command will generate the iOS and Android native projects required for the ContactsManager SDK to work. After running prebuild:

The ios directory will be created/updated with CocoaPods setup
The android directory will be created/updated with Gradle setup

Make sure to run prebuild again if you make changes to your native dependencies.

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

Add the following permissions to your android/app/src/main/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" />

Ensure your app’s minSdkVersion in android/build.gradle is at least 21:

buildscript {
    ext {
        minSdkVersion = 23
    }
}

SDK Initialization (Recommended)

import { initializeWithToken, isInitialized } from '@contactsmanager/rn';

// Check if already initialized
const alreadyInitialized = await isInitialized();

// Initialize with server-generated token (RECOMMENDED)
const result = await initializeWithToken("server-generated-token", {
  verboseLogging: false,
  autoSyncEnabled: true
});

// Basic Usage Example
import { requestContactsAccess, hasContactsReadAccess, getContacts } from '@contactsmanager/rn';

const requestAccess = async () => {
  try {
    const { granted } = await requestContactsAccess();
    if (granted) {
      const hasReadAccess = await hasContactsReadAccess();
      if (hasReadAccess) {
        const contacts = await getContacts();
        console.log(`Retrieved ${contacts.length} contacts`);
      }
    }
  } catch (error) {
    console.error('Error accessing contacts:', error);
  }
};

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 (Recommended)

#import <ContactsManager/ContactsManager.h>

// Initialize with options (optional)
CMContactsManagerOptions *options = [CMContactsManagerOptions defaultOptions];
options.verboseLogging = NO;
options.autoSyncEnabled = YES;

// Initialize the service with server-generated token (RECOMMENDED)
[[CMContactService sharedInstance] initializeWithToken:@"server-generated-token"
                                                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 (Recommended)

// Initialize the library
private val contactService by lazy { ContactService.getInstance(context) }

// Create options
val options = CMContactsManagerOptions.defaultOptions().apply {
    verboseLogging = false
    autoSyncEnabled = true
}

// Initialize the service with server-generated token (RECOMMENDED)
val initResult = contactService.initializeWithToken(
    token = "server-generated-token",
    options = options
)

if (initResult.isSuccess) {
    // Service initialized successfully
    val userInfo = initResult.data
} else {
    // Handle initialization error
    val error = initResult.error
}

Next Steps

Accessing the API

Learn how to access and use the ContactsManager SDK API

Contacts Authorization

Request and manage access to device contacts

Search UI

Build powerful contact search interfaces

Recommendations

Implement intelligent contact recommendations

Get Started

Features

Services

Webhooks

Models

​Installation

​1. Fast Installation (Client Only)

​Swift Package Manager

​SDK Initialization (Development Only)

​Installation

​SDK Initialization (Development Only)

​SDK Initialization (Development Only)

​SDK Initialization (Development Only)

​2. Full Installation (Recommended)

​Step A: Server Setup

​Installation

​Create User (First Time Setup)

​Generate Token (Subsequent Logins)

​Installation

​Create User (First Time Setup)

​Generate Token (Subsequent Logins)

​Step B: Client Setup

​Swift Package Manager

​SDK Initialization (Recommended)

​Installation

​Expo Setup

​Platform Setup

iOS Setup

Android Setup

​SDK Initialization (Recommended)

​Installation

​SDK Initialization (Recommended)

​Installation

​Get Latest Version

​Required Permissions

​SDK Initialization (Recommended)

​Next Steps

Accessing the API

Contacts Authorization

Search UI

Recommendations

Installation

1. Fast Installation (Client Only)

Swift Package Manager

SDK Initialization (Development Only)

Installation

SDK Initialization (Development Only)

SDK Initialization (Development Only)

SDK Initialization (Development Only)

2. Full Installation (Recommended)

Step A: Server Setup

Installation

Create User (First Time Setup)

Generate Token (Subsequent Logins)

Installation

Create User (First Time Setup)

Generate Token (Subsequent Logins)

Step B: Client Setup

Swift Package Manager

SDK Initialization (Recommended)

Installation

Expo Setup

Platform Setup

SDK Initialization (Recommended)

Installation

SDK Initialization (Recommended)

Installation

Get Latest Version

Required Permissions

SDK Initialization (Recommended)

Next Steps