Alexa Auto Contacts ¶
The Alexa Auto Contacts library is an Android library used by the Alexa Auto App to fetch contact information from the vehicle's head unit and send it to Alexa. The AACS Core Service can also use this library to remove from Alexa the uploaded contact information.
Table of Contents¶
- Overview
- Setup for Alexa Auto App Contacts Library
- Providing Permission in Android Manifest
- Specifying Intent Targets
- Sequence Diagrams
- How the Alexa Auto App Contacts Library Works with an Address Book
- Uploading Address Book
- Removing Address Book
Overview¶
The Contacts Library enables the Alexa Auto App to interact with the Auto SDK Engine easily to add or remove an address book, which contains all contact information maintained by the Android Contacts Provider. For information about Contacts Provider, see the Contacts Provider documentation.
Note: An address book can be of the type Contact or Navigation. The Contacts Library only works with the Contact type. For example, AACS cannot use the library to fetch data about a navigation favorite. See the Auto SDK
Address Book
module documentation for more information about theAddressBookType
API.
The following list describes the major components of the library:
-
The AACS Contacts Service is responsible for:
- Receiving AASB
AddAddressBook
orRemoveAddressBook
messages from the AACS Core Service. - Receiving defined intents from your application to upload or remove an address book
- Receiving AASB
-
The Alexa Auto App Contacts Library platform implementation (
PhoneBookController
) is responsible for:- Fetching the address book from the Android Contacts Provider
- Parsing all contact data from the address book into an AASB
AddAddressBook
message - Sending the AASB
AddAddressBook
intent to the AACS Core Service to upload the address book to Alexa - Sending the AASB
RemoveAddressBook
intent to the AACS Core Service to remove from Alexa an address book with a specificaddressBookSourceId
, a unique address book identifier defined in the Address Book handler (Bluetooth MAC address of connected phone) - Providing the API for adding or removing an address book for your application to call
Setup for Alexa Auto App Contacts Library¶
Before using the Alexa Auto App Contacts Library, follow these major steps:
- Provide permission in your application's Android manifest.
- Specify targets for intents from the AACS Core Service.
Providing Permission in Android Manifest¶
For security reasons, for your application to send intents to or receive intents from the AACS Contacts Service, specify the com.amazon.aacscontacts
permission in your application's Android manifest as follows:
<uses-permission android:name="com.amazon.aacscontacts" />
Specifying Intent Targets¶
The AACS Contacts Service listens to intents from the AACS Core Service with the AddressBook
topic. To specify AACS Contacts Service with an intent target for the AddressBook
topic, follow one of these steps:
- Manually specify the messages in the Alexa Auto App configuration file, as described in the AACS README. The targets in the Alexa Auto APp configuration file override the ones specified by intent filters. The following example shows how to specify an intent target in the Alexa Auto APp configuration file. In this example, the Alexa Auto App Contacts Library AAR is part of the AACS APK.
"AddressBook" : {
"type": ["<target_1_type>", "SERVICE", ...],
"package": ["<target_1_package_name>", "com.amazon.alexaautoclientservice", ...],
"class": ["<target_1_class_name>", "com.amazon.aacscontacts.AACSContactsService", ...]
}
- Omit ANY targets for
AddressBook
in the Alexa Auto App configuration file. As a result, the intent filter defined in the Alexa Auto App Contacts Library takes effect, enabling the AACS Contacts Service to receive the intents.
Sequence Diagrams¶
The following diagram illustrates the flow when an address book is uploaded to Alexa.
The following diagram illustrates the flow when an address book is removed from Alexa.
How the Alexa Auto App Contacts Library Works with an Address Book¶
This section describes how the Contacts Library uploads or removes an address book.
Uploading Address Book¶
Use one of the following methods to upload an address book to Alexa:
-
Use intent. Your application can inform the Alexa Auto App Contacts Library to upload an address book to Alexa by using an intent. When the Alexa Auto App Contacts Library receives the intent, the library fetches contacts from the Contacts Provider on the head unit and uploads them to Alexa. To determine whether the upload is successful, your application can subscribe to the AASB
AddressBook
intents. Define the attributes of the intent as follows:- Action is
com.amazon.aacscontacts.upload
. - Category is
com.amazon.aacscontacts
. - Extras is
addressBookSourceId
(Must be Bluetooth MAC address from connected phone fetched from client application) and the name of the address book (defined in the Address Book platform interface), specified as follows:
- Action is
{
"addressBookSourceId": "<addressBookSourceId>",
"addressBookName": "<Name of phone book>"
}
- Use a direct API call. This method is applicable only if you put the Alexa Auto App Contacts Library in your application. The
PhoneBookController.uploadContacts
API blocks the current thread and returns a boolean value indicating if the operation is successful. The following code shows how to usePhoneBookController.uploadContacts
:
// Instantiate PhoneBookController
PhoneBookController phoneBookController = new PhoneBookController(context);
Boolean succeeded = phoneBookController.uploadContacts(addressBookSourceId, addressBookName);
addressBookSourceId
must be Bluetooth MAC address from connected phone fetched from client application in order to have contacts upload working properly
Removing Address Book¶
Use one of the following methods to remove an address book from Alexa:
-
Use intent. Your application can inform the AACS Contacts Service to remove an address book from Alexa by using an intent. Define the attributes of the intent as follows:
-
Action is
com.amazon.aacscontacts.remove
. - Category is
com.amazon.aacscontacts
. - Extras is
addressBookSourceId
(defined in the Address Book platform interface), specified as follows:
{
"addressBookSourceId": "<addressBookSourceId>"
}
- Use a direct API call. This method is applicable only if you put the Alexa Auto App Contacts Library in your application. The
PhoneBookController.removeContacts
API blocks the current thread and returns a boolean value indicating if the operation is successful. The following code shows how to usePhoneBookController.removeContacts
:
// Instantiate PhoneBookController
PhoneBookController phoneBookController = new PhoneBookController(context);
Boolean succeeded = phoneBookController.removeContacts(addressBookSourceId);
addressBookSourceId
must be Bluetooth MAC address from connected phone fetched from client application in order to have contacts remove working properly