Native Contacts

The Despia Contacts SDK allows your app to securely access and manage user contacts with minimal implementation effort. This guide walks you through the process of requesting permissions, retrieving contacts, and handling the retrieved data.

Quick Start

1. Request Contact Permission

First, you need to request permission from the user to access their contacts. This triggers the native permission dialog on the user's device:

Copywindow.despia = "requestcontactpermission://"

2. Read Contacts

After permission is granted, you can request to read the user's contacts:

Copywindow.despia = "readcontacts://"

3. Handle Contact Data

Despia injects contact data into your application's window object. To detect when this data becomes available, we suggest you use the provided observer function:

Copyfunction observeDespiaVariable(variableName, callback, timeout = 5000) {
    const startTime = Date.now();
    
    function checkVariable() {
        if (window[variableName] !== undefined) {
            callback(window[variableName]);
        } else if (Date.now() - startTime < timeout) {
            setTimeout(checkVariable, 100);
        } else {
            console.error(`Despia timeout: ${variableName} was not set within ${timeout} ms`);
        }
    }
    
    checkVariable();
}

// Example usage
observeDespiaVariable("contacts", function(contacts) {
    console.log(contacts); // Process contacts data if using regular JavaScript
    
    // EXAMPLES FOR NO-CODE/LOW-CODE TOOLS
    
    // ---------- WEWEB ----------
    // WEWEB example using wwWorkflow to handle contacts data
    
    // 1. Create a Native WeWeb Global Workflow to receive contacts data
    // 2. Add Logic to that Workflow to process the contacts as needed
    // 3. Call your Workflow from exactly this line of code here:
    wwLib.wwWorkflow.executeGlobal('YOUR WEWEB WORKFLOW ID', {
        contacts: contacts
    });
    
    // ---------- WIZED ---------- 
    // WIZED example using Wized's JS API
    v.contactsData = contacts;
   
    // Create a request (API Call) that will send contacts to your server
    const result = await Wized.requests.execute('REQUEST NAME TO PROCESS CONTACTS');
    console.log(result); // Or set result as variable if needed

    // ---------- NORDCRAFT / TODDLE ---------- 
    // For Nordcraft / Toddle - simply install the "Despia" Package and listen for the event callback.
    // Clone the package from here: https://toddle.dev/projects/despia_package/branches/main
    // Or run following after registering an "onCallback" Event in your Custom Action:
    ctx.triggerActionEvent("onCallback", contacts);
});

How It Works

1. Permission Request:

   • The SDK sends a permission request to the device's native contact system

   • The user sees a standard system permission dialog

   • The result (granted/denied) is handled by the SDK

2. Contact Retrieval:

   • When readcontacts:// is called, the SDK accesses the device's contact database

   • Contacts are formatted into a consistent structure across platforms

   • The data is injected into your app's window object as window.contacts

3. Data Handling:

   • The observeDespiaVariable function polls for the contacts variable

   • Once the variable is detected, your callback function is triggered

   • If the data isn't available within the timeout period, an error is logged

Function Parameters

observeDespiaVariable

Best Practices

Permission Handling

• Always check for existing permissions before requesting new ones

• Handle permission denial gracefully

• Provide clear messaging to users about why contact access is needed

Error Handling

• Implement proper error handling for timeout scenarios

• Handle cases where contacts might be empty or malformed

• Log errors appropriately for debugging

Performance

• Consider implementing retry logic for failed requests

• Cache contact data when appropriate

• Use the timeout parameter appropriately based on your app's needs

Complete Implementation Example

Here's a complete implementation that includes permission requesting, contact reading, and error handling:

Copy// Request permission
window.despia = "requestcontactpermission://";

// Setup contact retrieval with error handling
function retrieveContacts() {
    try {
        window.despia = "readcontacts://";
        
        observeDespiaVariable("contacts", function(contacts) {
            if (!contacts) {
                console.error("No contacts data received");
                return;
            }
            
            // Process contacts
            processContacts(contacts);
        });
    } catch (error) {
        console.error("Error retrieving contacts:", error);
    }
}

function processContacts(contacts) {
    // Implement your contact processing logic here
    console.log("Contacts retrieved successfully:", contacts);
}

Contact Data Structure

The contacts data is provided as an array of contact objects. Each contact object contains standardized fields:

Copy{
  "John Appleseed": [
    "+12345678910"
  ],
  "Ann Wilson": [
    "+12345678910"
  ]
}

Troubleshooting

Common Issues

Permission Denied

• Verify that your app has the proper permission declarations

• Check if the user has previously denied permissions

• Implement a retry strategy with user guidance

Timeout Errors

• Check network connectivity

• Verify that the SDK is properly initialized

• Consider increasing the timeout value

Empty Contact List

• Verify that the device has contacts

• Check if contacts sync is enabled on the device

• Validate permission status