Contact Access

Overview

The native contacts feature allows your app to request permission to access the device's contact list and retrieve contact information including names and phone numbers. This is useful for social features, contact importing, or any functionality requiring access to the user's address book.

Prerequisites

Before implementing contact access, ensure you have:

1. Installed the Despia plugin from the WeWeb Marketplace (free)

2. Verified installation by checking Assets → Library → look for the bookmark symbol showing "Despia Provider"

Implementation Steps

Step 1: Add the Despia Plugin Component

1. Click the Add button in your WeWeb editor

2. Navigate to the Assets panel

3. Find and drag the Despia plugin element onto your page

   • Works on both new and existing pages

   • Best practice: Place at the top of the page for visibility

Step 2: Create a Contacts Variable

1. Create a new variable named "contacts"

2. Set type to Array

3. Initialize with an empty array []

Step 3: Add Permission Request Button

1. Add a button element to your page

2. Label it "Request Contacts" or similar

3. Go to the button's Workflows

4. Add a new workflow with "On click" trigger

5. Add action: Execute component action

   • Component: Select "Despia plugin"

   • Action: Choose "Request native Contacts, no callback"

Step 4: Add Read Contacts Button

1. Add another button element

2. Label it "Read Contacts"

3. Go to Workflows → Add new "On click" workflow

4. Add action: Execute component action

   • Component: Select "Despia plugin"

   • Action: Choose "Read native Contacts, callback an event"

Step 5: Handle Contact Data Callback

1. Select the Despia plugin component on your page

2. Go to Workflows → Add new workflow

3. Change trigger from "On click" to "On Contacts change"

4. Add action: Change variable value

   • Variable: Select your "contacts" variable

   • Value: Bind to Event > data (contains the contact array)

Step 6: Display Contacts (Optional)

To display the retrieved contacts:

1. Add a List element to your page

2. Bind the list to repeat on your "contacts" variable

3. Inside each list item:

   • Add a Text element for the contact name

   • Bind to item > name

4. For phone numbers (if multiple per contact):

   • Add a nested List inside each contact item

   • Bind to repeat on item > numbers

   • Display each number in the nested list

Data Structure

The contacts data returned has the following structure:

Copy[
  {
    "name": "Contact Name",
    "numbers": ["phone1", "phone2"]
  }
]

Publishing & Testing

1. Click Publish in WeWeb to deploy your changes

2. Changes are automatically available via over-the-air updates

3. No app rebuild or App Store resubmission required

4. Test on a real device (contacts won't load in browser preview)

Important Considerations

Permissions

• First-time users will see a system permission dialog

• If already granted, the request button won't show another dialog

• iOS users can grant full or limited access to contacts

Privacy & Compliance

• Always obtain user consent before accessing contacts

• Clearly explain why you need contact access

• Follow privacy regulations (GDPR, CCPA, etc.)

• Store contact data securely if sending to backend

Handling Permission States

Tip: If unsure about permission status:

• Try reading contacts without requesting first

• If no data returns within ~10 seconds, permission likely not granted

• Then prompt user to grant permission

Best Practices

• Request permissions contextually: Only ask when the user needs the feature

• Explain the value: Tell users why you need contact access before requesting

• Handle rejection gracefully: Provide alternative workflows if permission denied

• Respect privacy: Only access contacts when necessary

• Secure data transmission: Encrypt contact data when sending to backend

Common Use Cases

• Social features: Find friends already using your app

• Contact import: Quick contact list building

• Sharing features: Easy sharing with contacts

• Event invitations: Send invites to contacts

• Emergency contacts: Quick access for safety features

Troubleshooting

• Empty contact list: User may have denied permission or has no contacts

• Missing phone numbers: Some contacts may not have numbers saved

• Permission dialog not showing: Permission may already be granted/denied

• Data not updating: Ensure the callback workflow is properly configured