Accessing the API

How to access and use the ContactsManager SDK API

Installation

Install and initialize the ContactsManager SDK in your client application.

Swift

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:

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

import ContactsManager

// Create user information
let userInfo = UserInfo(
    userId: "user-123",
    email: "[e-mail]",
    phone: "[phone]",
    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()

Accessing the Service

The ContactsManager SDK provides a comprehensive API through the ContactsService class. Here’s how to access and use the service:

Swift

// Access the shared instance
let service = ContactsService.shared

// Check initialization status
let isInitialized = service.isInitialized

// Get current state
let state = service.currentState

Error Handling

The SDK provides comprehensive error handling across all platforms:

Swift

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

Important: Secure Your Users’ Data

Server-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:

1. API Key verification
2. 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.