# Address Book

Essential Kit's Address Book feature lets Unity teams read device contacts, detect friends already playing, and power invite flows without maintaining platform-specific code. This tutorial covers setup, permissions, core APIs, testing, and troubleshooting so you can safely build contact-powered experiences.

{% hint style="info" %}
Using PlayMaker? See the PlayMaker guide: [PlayMaker](/features/address-book/playmaker.md).
{% endhint %}

{% embed url="<https://www.youtube.com/watch?v=Tv85rRIYY_4>" %}
Address Book Video Tutorial
{% endembed %}

{% hint style="info" %}
Looking for a working reference? Open the demo scene at `Assets/Plugins/VoxelBusters/EssentialKit/Examples/Scenes/AddressBookDemo.unity` and the companion script at `Assets/Plugins/VoxelBusters/EssentialKit/Examples/Scripts/AddressBookDemo.cs` to see the full API in action.
{% endhint %}

## What You'll Learn

* Request contacts access with a custom rationale screen and handle every permission state
* Read and filter contacts with `ReadContactsOptions` plus pagination for large address books
* Load contact properties (names, numbers, emails, thumbnails) and recover when access is denied

## Why Address Book Matters

* **Social Growth**: Find friends already playing and drive invite-a-friend loops or referral rewards
* **Faster UX**: Autofill player names, email fields, or support forms directly from saved contacts
* **Cross-Platform**: One API spans iOS Contacts and Android Contacts Provider, including limited access states

## Tutorial Roadmap

1. [Setup](/features/address-book/setup.md) – Enable the feature, configure permissions, and assign placeholder assets
2. [Usage](/features/address-book/usage.md) – Handle permission prompts, read contacts, filter data, and load images
3. [Testing](/features/address-book/testing.md) – Validate behaviour in the simulator and on real devices
4. [FAQ](/features/address-book/faq.md) – Troubleshoot permissions, pagination, and missing data

## Key Use Cases

* Detect friends already playing and light up invite buttons in onboarding
* Trigger referral rewards when a player texts or emails selected contacts
* Show contact pickers inside support flows to auto-fill recipient details
* Populate co-op lobbies with verified phone numbers or emails for quick invites

## Prerequisites

* Unity project with Essential Kit v3 installed and Address Book enabled in Essential Kit Settings
* iOS targets require a clear `NSContactsUsageDescription` explaining why contacts are needed
* Android targets rely on system-managed permission prompts; plan supporting UI copy in-game
* Test devices (or the Essential Kit simulator) to validate permission flows before release

{% content-ref url="/pages/2aVEXcMQdho7gaYPD8Ff" %}
[Setup](/features/address-book/setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MJoMcEatijf\_luXdQm3" %}
[Usage](/features/address-book/usage.md)
{% endcontent-ref %}

{% content-ref url="/pages/HIbQMas1eq21GEzQbQNN" %}
[Testing](/features/address-book/testing.md)
{% endcontent-ref %}

{% content-ref url="/pages/T5oW3ynfLkHZ4IItyVm2" %}
[FAQ](/features/address-book/faq.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://assetstore.essentialkit.voxelbusters.com/features/address-book.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.