FAQ

Setup and Permissions

Do we need to manually add the required permissions?

No. Essential Kit automatically handles all required permissions:

iOS: Adds NSContactsUsageDescription to Info.plist
Android: Adds READ_CONTACTS permission to AndroidManifest.xml

You only need to provide the usage description text in Essential Kit Settings for privacy compliance.

What should I put in the usage description?

Write a clear explanation of why your game needs contact access:

Good: "Find friends who are already playing the game"
Good: "Invite contacts to join multiplayer matches"
Bad: "This app needs access to contacts"

If user denies contacts access permission, how do I proceed?

Explain the benefit before requesting permission
Handle denial gracefully - provide alternative features
Guide to settings if needed: Use Utilities.OpenApplicationSettings() to help users change permissions manually

if (status == AddressBookContactsAccessStatus.Denied)
{
    // Show explanation and option to open settings
    Debug.Log("Contact access denied. Opening settings...");
    Utilities.OpenApplicationSettings();
}

Reading Contacts

Why am I getting zero contacts returned?

Common causes:

No permission granted - Check GetContactsAccessStatus() first
Device has no contacts - Test with contacts added to device
Constraints too restrictive - Try reading without constraints first
Limit set too low - Increase the limit or remove it

How do I handle large contact lists efficiently?

Use pagination to load contacts in smaller batches:

var options = new ReadContactsOptions.Builder()
    .WithLimit(50)  // Load 50 at a time
    .WithOffset(currentOffset)
    .Build();

Can I search for specific contacts by name?

Essential Kit doesn't provide search functionality. Read contacts and filter them in your code:

var matchingContacts = contacts.Where(c => 
    c.FirstName?.Contains("John") == true || 
    c.LastName?.Contains("John") == true
).ToArray();

Why are some contacts missing names or emails?

Not all contacts have complete information. Always check for null/empty values:

if (!string.IsNullOrEmpty(contact.FirstName) || !string.IsNullOrEmpty(contact.LastName))
{
    // Contact has at least one name
}

if (contact.EmailAddresses?.Length > 0)
{
    // Contact has email addresses
}

Contact Properties

How do I display contact names properly?

Handle various name scenarios:

string GetDisplayName(IAddressBookContact contact)
{
    if (!string.IsNullOrEmpty(contact.FirstName) && !string.IsNullOrEmpty(contact.LastName))
        return $"{contact.FirstName} {contact.LastName}";
    else if (!string.IsNullOrEmpty(contact.FirstName))
        return contact.FirstName;
    else if (!string.IsNullOrEmpty(contact.LastName))
        return contact.LastName;
    else if (!string.IsNullOrEmpty(contact.CompanyName))
        return contact.CompanyName;
    else
        return "Unknown Contact";
}

Why aren't contact images loading?

Contact images are optional and may not exist:

Not all contacts have profile photos
Loading is asynchronous - use the callback properly
Permission issues - ensure contacts permission is granted

contact.LoadImage((textureData, error) =>
{
    if (error == null && textureData != null)
    {
        // Successfully loaded - use textureData.Texture
    }
    else
    {
        // No image or loading failed - use default image
    }
});

No. Essential Kit only accesses device contact data. It doesn't integrate with social media platforms for additional photos.

Platform Differences

Are there differences between iOS and Android?

The API is unified, but there are some platform behaviors:

iOS:

Permission dialog appears first time you call ReadContacts()
Users can grant "Limited" access in iOS 14+
Contact data includes more detailed information

Android:

Runtime permission request on Android 6.0+
May require multiple permission grants on some devices
Contact data varies by device manufacturer

Does this work on Unity Editor?

Yes! Essential Kit provides editor simulation:

Go to Window → Voxel Busters → Essential Kit → Simulator Database
Configure permission status and add test contacts
Test your implementation without deploying to device

Performance and Optimization

How do I optimize contact loading for better performance?

Use appropriate limits: Don't load all contacts at once
Apply constraints: Filter by required data fields
Load images selectively: Only load images when needed
Cache results: Store contacts locally to avoid repeated API calls

// Optimized approach
var options = new ReadContactsOptions.Builder()
    .WithLimit(25)  // Reasonable batch size
    .WithConstraints(ReadContactsConstraint.MustIncludeName)  // Only contacts with names
    .Build();

Should I cache contact data?

Considerations:

Pro: Faster subsequent access
Con: Contact data can become outdated
Pro: Reduces permission requests
Con: Privacy concerns with storing personal data

Recommendation: Cache only essential data (names, IDs) and refresh periodically.

Troubleshooting

ReadContacts callback never gets called

Check these issues:

Permission denied silently - Verify permission status first
Device has no contacts - Test with contacts added
Threading issues - Ensure callback is handled properly

Getting "Unknown error" from Address Book

Common solutions:

Restart app after changing permissions
Check device storage - Low storage can cause issues
Test on different device - Some devices have contact access restrictions
Verify Essential Kit setup - Ensure feature is enabled in settings

Address Book works in editor but not on device

Verification steps:

Check build settings - Ensure target platform is set correctly
Verify permissions - Usage descriptions must be set in Essential Kit Settings
Test permission flow - Ensure user grants permission on device
Check device contacts - Ensure target device has contacts to read

Best Practices

When should I request contact access?

Good timing:

When user taps "Invite Friends" button
During social feature onboarding
When setting up multiplayer matching

Bad timing:

Immediately on app launch
Before explaining the benefit
Without user action triggering it

How do I make contact access feel natural?

Explain the benefit clearly before requesting
Provide alternative options if access is denied
Show progress while loading contacts
Handle errors gracefully with helpful messages
Respect user privacy - only access what you need

Last updated 14 days ago

Was this helpful?