> ## 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.

# Quickstart

> Get started with Contacts Manager in minutes

## Installation

ContactsManager offers two installation approaches. For production applications, we **strongly recommend** the [Full Installation](#2-full-installation-recommended) approach with server-side token generation.

### 1. Fast Installation (Client Only)

<Tabs>
  <Tab title="Swift">
    #### Swift Package Manager

    Add the ContactsManager package to your Swift project by adding it as a dependency in your `Package.swift` file:

    ```swift theme={null}
    dependencies: [
        .package(url: "https://github.com/arpwal/contactsmanager-ios.git", from: "<latest-version>")
    ]
    ```

    #### SDK Initialization (Development Only)

    ```swift theme={null}
    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
        )
    )
    ```
  </Tab>

  <Tab title="React Native">
    #### Installation

    ```bash theme={null}
    npm install @contactsmanager/rn
    # or
    yarn add @contactsmanager/rn
    ```

    #### SDK Initialization (Development Only)

    ```javascript theme={null}
    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
    });
    ```
  </Tab>

  <Tab title="Objective-C">
    #### SDK Initialization (Development Only)

    ```objc theme={null}
    #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);
        }
    }];
    ```
  </Tab>

  <Tab title="Kotlin">
    #### SDK Initialization (Development Only)

    ```kotlin theme={null}
    // 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
    }
    ```
  </Tab>
</Tabs>

### 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.

<Tabs>
  <Tab title="Python">
    #### Installation

    ```bash theme={null}
    pip install contactsmanager
    ```

    The Python SDK is open source and available on GitHub: [github.com/arpwal/contactsmanager-py](https://github.com/arpwal/contactsmanager-py)

    #### Create User (First Time Setup)

    ```python theme={null}
    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)

    ```python theme={null}
    # 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"]
    ```
  </Tab>

  <Tab title="Node.js">
    #### Installation

    ```bash theme={null}
    npm install @contactsmanager/server
    ```

    The Node.js SDK is open source and available on GitHub: [github.com/arpwal/contactsmanager-nodejs](https://github.com/arpwal/contactsmanager-nodejs)

    Full documentation for the Node.js SDK is also available on [npm](https://www.npmjs.com/package/@contactsmanager/server).

    #### Create User (First Time Setup)

    ```javascript theme={null}
    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)

    ```javascript theme={null}
    // 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;
    }
    ```
  </Tab>
</Tabs>

#### Step B: Client Setup

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

<Tabs>
  <Tab title="Swift">
    #### Swift Package Manager

    Add the ContactsManager package to your Swift project by adding it as a dependency in your `Package.swift` file:

    ```swift theme={null}
    dependencies: [
        .package(url: "https://github.com/arpwal/contactsmanager-ios.git", from: "<latest-version>")
    ]
    ```

    Or in Xcode:

    1. Go to File > Swift Packages > Add Package Dependency
    2. Enter the repository URL: `https://github.com/arpwal/contactsmanager-ios.git`
    3. Specify a minimum version of `<latest-version>` from the repository
    4. Click Next and complete the integration

    #### SDK Initialization (Recommended)

    ```swift theme={null}
    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
        )
    )
    ```

    <Note>
      **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.
    </Note>
  </Tab>

  <Tab title="React Native">
    #### Installation

    ```bash theme={null}
    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:

    ```bash theme={null}
    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

    1. Install CocoaPods dependencies:

    ```bash theme={null}
    cd ios && pod install && cd ..
    ```

    2. Add permissions to `Info.plist`:

    ```xml theme={null}
    <key>NSContactsUsageDescription</key>
    <string>We need access to your contacts to enable social features</string>
    ```

    ##### Android Setup

    1. Add the following permissions to your `android/app/src/main/AndroidManifest.xml`:

    ```xml theme={null}
    <!-- 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" />
    ```

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

    ```gradle theme={null}
    buildscript {
        ext {
            minSdkVersion = 23
        }
    }
    ```

    #### SDK Initialization (Recommended)

    ```javascript theme={null}
    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);
      }
    };
    ```
  </Tab>

  <Tab title="Objective-C">
    #### Installation

    1. Download the latest `ContactsManager.framework` from [Releases](https://github.com/arpwal/contactsmanager-objc/releases)
    2. Drag and drop the framework into your Xcode project
    3. Add framework to "Link Binary With Libraries" in Build Phases
    4. Add to Info.plist:

    ```xml theme={null}
    <key>NSContactsUsageDescription</key>
    <string>We need access to contacts to enable social features.</string>
    ```

    #### SDK Initialization (Recommended)

    ```objc theme={null}
    #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);
        }
    }];
    ```
  </Tab>

  <Tab title="Kotlin">
    #### Installation

    Add the library to your project's `build.gradle`:

    ```gradle theme={null}
    implementation("io.contactsmanager:contactsmanager:1.0.5")
    ```

    #### Get Latest Version

    You can check for the latest version of the SDK on [Maven Central](https://central.sonatype.com/artifact/io.contactsmanager/contactsmanager/overview).

    #### Required Permissions

    Add the following permissions to your `AndroidManifest.xml`:

    ```xml theme={null}
    <!-- 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)

    ```kotlin theme={null}
    // 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
    }
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Accessing the API" icon="code" href="/services/accessing-api">
    Learn how to access and use the ContactsManager SDK API
  </Card>

  <Card title="Contacts Authorization" icon="shield-check" href="/services/contacts-authorization">
    Request and manage access to device contacts
  </Card>

  <Card title="Search UI" icon="magnifying-glass" href="/services/search-ui">
    Build powerful contact search interfaces
  </Card>

  <Card title="Recommendations" icon="user-plus" href="/services/recommendations">
    Implement intelligent contact recommendations
  </Card>
</CardGroup>