​
Local Canonical Contact

The LocalCanonicalContact model bridges the gap between local device contacts and server-side user profiles. It provides a way to link a contact on the user’s device with their canonical representation in your app’s ecosystem, enabling powerful social features.

​
Properties

  • contact: Contact? - The local device contact information
  • contactId: String - Unique identifier for the local contact
  • sourceContactId: String - External identifier in the local database
  • canonicalContact: CanonicalContact - Server-side canonical profile information

​
Usage Example

// Getting app users (contacts who are already using the app)
func displayAppUsers() async {
    do {
        let appUsers = try await ContactsService.shared.getContactsUsingApp(limit: 20)
        
        for user in appUsers {
            // Access local contact info if available
            if let localContact = user.contact {
                print("Local contact: \(localContact.displayName ?? "Unknown")")
                
                // Get their local phone numbers
                for phone in localContact.phoneNumbers {
                    print("Phone: \(phone.value ?? "None")")
                }
            }
            
            // Access server-side user profile info
            let canonicalUser = user.canonicalContact
            print("User profile: \(canonicalUser.fullName)")
            print("Organization user ID: \(canonicalUser.organizationUserId)")
            
            // You can use the organization user ID for social features
            await followUser(userId: canonicalUser.organizationUserId)
        }
    } catch {
        print("Error getting app users: \(error.localizedDescription)")
    }
}

// Follow a user using their organization user ID
func followUser(userId: String) async {
    do {
        let result = try await ContactsService.shared.socialService.followUser(
            userId: userId
        )
        
        if let success = result.success, success {
            print("Successfully followed user")
        }
    } catch {
        print("Error following user: \(error.localizedDescription)")
    }
}

​
Understanding Local vs. Canonical Contacts

The relationship between local and canonical contacts is fundamental to the ContactsManager SDK:

  1. Local Contacts (Contact) exist only on the user’s device and contain device-specific information like phone numbers and email addresses.

  2. Canonical Contacts (CanonicalContact) are server-side representations of users in your app’s ecosystem, with consistent identities across all devices.

  3. Local Canonical Contacts (LocalCanonicalContact) create the mapping between these two worlds, enabling your app to:

    • Show which of a user’s contacts are also using your app
    • Provide consistent identity for users across multiple devices
    • Enable social features like follow/unfollow and activity feeds
    • Maintain privacy by keeping sensitive contact details on the device

This separation provides both privacy and powerful social features by only sharing the minimal information needed for user identification across devices.