Using the “Find Your Friends” feature, users can upload their address book to find other Digits users in your app that they know.

Getting started

The “Find Your Friends” feature is accessible through the DGTContacts class. Provide the initializer with a user session of the type DGTSession, which can be obtained from the Digits shared instance [Digits sharedInstance].session.

To start the “Find Your Friends” process call one of the startContactsUploadWith... methods. Variations are available to override properties such as custom appearance, title, or presenting view controller.

// Objective-C
DGTSession *userSession = [Digits sharedInstance].session;
DGTContacts *contacts = [[DGTContacts alloc] initWithUserSession:userSession];

[contacts startContactsUploadWithCompletion:^(DGTContactsUploadResult *result, NSError *error) {
   // Inspect results and error objects to determine if upload succeeded.
}];

// Swift
let userSession = Digits.sharedInstance().session;
let contacts = DGTContacts(userSession: userSession);

contacts.startContactsUpload() { result, error in
  // Inspect results and error objects to determine if upload succeeded.
}

Address book access

The first time startContactsUploadWith... is called, Digits will display a modal UI requesting permission to upload the user’s address book.

Permissions control flow

If the user taps “OK”, the user will be prompted by the system for Address Book permission. If the user grants permission, their address book will uploaded in the background and the modal UI will dismiss immediately.

If the user taps “Not now”, the modal UI will dismiss and Digits will report DGTErrorCodeUserCanceledFindContacts to the callback’s error argument.

If the user taps “OK”, but then does not grant your app access to their address book, the modal UI will dismiss and Digits will report DGTErrorCodeUserDeniedAddressBookAccess to the callback’s error argument.

Note:

Subsequent calls to startContactsUploadWith... will not display the modal UI if the user has previously granted or denied access to their address book. If the user tapped “Not now”, then the modal UI will be displayed again. Call -[DGTContacts contactsAccessAuthorizationStatus] to determine whether or not the modal UI will display.

Once the address book upload finishes, the provided callback will be called containing a DGTContactsUploadResult object or an error that occurred. The DGTContactsUploadResult object contains properties for totalContacts and numberOfUploadedContacts to describe how many contacts were uploaded and how many were actually uploaded successfully. Note that the DGTContactsUploadResult object will be nil if the upload fails.

Finding matches

Once a user has uploaded their contacts, Digits can lookup address book matches with other Digits users by calling lookupContactMatchesWithCursor:completion:. Matches will return the Digits userID’s of users of your app that the authenticated user knows and any other users of your app that may know your user.

The optional cursor argument can be used to offset the returned matches from a prior request. For example, if after the first request the nextCursor in the callback is not nil and 100 matches were found, pass the given nextCursor to a second call of this method to retrieve the second 100 matches (if any).

// Objective-C
DGTSession *userSession = [Digits sharedInstance].session;
DGTContacts *contacts = [[DGTContacts alloc] initWithUserSession:userSession];

[contacts lookupContactMatchesWithCursor:nil completion:^(NSArray *matches, NSString *nextCursor, NSError *error) {
  // matches is an Array of DGTUser objects
  // use nextCursor in a follow-up call to this method to offset the results
}];

// Swift
let userSession = Digits.sharedInstance().session;
let contacts = DGTContacts(userSession: userSession);

contacts.lookupContactMatches(cursor:nil) { matches, nextCursor, error in
  // matches is an Array of DGTUser objects
  // use nextCursor in a follow-up call to this method to offset the results
}

Deleting uploaded contacts

All of a user’s uploaded contacts can be deleted from Digits by calling deleteAllUploadedContactsWithCompletion.

Note:

After deleting a user’s contacts, calling lookupContactMatchesWithCursor:completion may still return matches. This is because of reverse lookup - if another Digits user has this user’s phone number in their address book, it would still be a match.

// Objective-C
DGTSession *userSession = [Digits sharedInstance].session;
DGTContacts *contacts = [[DGTContacts alloc] initWithUserSession:userSession];

[contacts deleteAllUploadedContactsWithCompletion:^(NSError *error) {
  // Inspect error to determine if delete succeeded
}];

// Swift
let userSession = Digits.sharedInstance().session;
let contacts = DGTContacts(userSession: userSession);

contacts.deleteAllUploadedContacts() { error in
  // Inspect error to determine if delete succeeded
}