Contacts SDK

Implementation Guide

1. Request Contact Permission

To request permission to access user contacts, use the following command:

window.despia = "requestcontactpermission://"

This will trigger the native permission dialog on the user's device.

2. Read Contacts

After permission is granted, you can read the contacts using:

window.despia = "readcontacts://"

3. Handling Contact Data

To handle the contact data after retrieval, use the provided observer function:

function 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
});

Parameters

observeDespiaVariable

• variableName (string): Name of the variable to observe (e.g., "contacts")

• callback (function): Function to execute when variable is set

• timeout (number): Maximum time to wait in milliseconds (default: 5000)

Best Practices

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

2. Error Handling

   • Implement proper error handling for timeout scenarios

   • Handle cases where contacts might be empty or malformed

   • Log errors appropriately for debugging

3. Performance

   • Consider implementing retry logic for failed requests

   • Cache contact data when appropriate

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

Example Implementation

// 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);
}

Troubleshooting

Common Issues

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

2. Timeout Errors

   • Check network connectivity

   • Verify that the SDK is properly initialized

   • Consider increasing the timeout value

3. Empty Contact List

   • Verify that the device has contacts

   • Check if contacts sync is enabled on the device

   • Validate permission status

Need help? Email us at support@despia.com