Sign In With Phone Number

Digits lets people create an account or sign into your app using nothing but their phone number on iOS and Android. Built using the same global, reliable infrastructure Twitter uses, Digits will verify the user’s phone number with a simple customizable user interface that easily integrates into your app.

Digits extends your existing user/profile database. A successful Digits account creation will return a stable userID to attach or match with your user record, and an oAuth token for the device. A verified phone number is also returned for convenience, but the user’s number may change at any time and should not be used for authentication.

Digits includes web login and signup support, as well as the ability for users to find their friends via their address books.

  • Access your account on Digits website <https://digits.com>
  • Phone numbers are rate limited to normal consumer usage.

Note

Digits authentication workflow screens are translated into the user’s OS language. SMS language is based on the user’s OS language at the time of sign-up.

Set Up a Digits Button

The first step in obtaining a Digits authentication token in your app is to add a button. Inside your layout, add a Digits button with the following code:

<com.digits.sdk.android.DigitsAuthButton
     android:id="@+id/auth_button"
     android:layout_width="wrap_content"
     android:layout_height="wrap_content" />

This will render a button that looks like:

../_images/digits-button.png

Configure the Button in an Activity

In the Activity or Fragment that displays the button, you need to create and attach an AuthCallback to the button. Digits keeps a weak reference to your implementation of AuthCallback, therefore you must keep a strong reference to it. For example you can keep a strong reference to your AuthCallback by implementing it in your Application instance.

// DemoApplication.java
public class DemoApplication extends Application {
  private AuthCallback authCallback

  @Override
  public void onCreate() {
    super.onCreate();
    TwitterAuthConfig authConfig =  new TwitterAuthConfig("consumerKey", "consumerSecret");
    Fabric.with(this, new TwitterCore(authConfig), new Digits.Builder().build());
    authCallback = new AuthCallback() {
      @Override
      public void success(DigitsSession session, String phoneNumber) {
          // Do something with the session
      }

      @Override
      public void failure(DigitsException exception) {
          // Do something on failure
      }
    }
  }

  public AuthCallback getAuthCallback(){
    return authCallback;
  }

}
// MainActivity.java
import com.digits.sdk.android.AuthCallback;
import com.digits.sdk.android.DigitsAuthButton;
import com.digits.sdk.android.DigitsException;
import com.digits.sdk.android.DigitsSession;
...

DigitsAuthButton digitsButton = (DigitsAuthButton) findViewById(R.id.auth_button);
digitsButton.setCallback(((DemoApplication) getApplication).getAuthCallback());

Provide a Phone Number

Digits exposes an API to allow a phone number to be passed into the authentication flow. Use authenticate(AuthConfig authConfig) and include a phone number, with optional country code to the AuthConfig.Builder(). Digits will attempt to parse out the country code and prepopulate both the country selector and phone number field. Note: the ‘+’ character is required for country code parsing:

AuthConfig.Builder authConfigBuilder = new AuthConfig.Builder()
                      .withAuthCallBack(callback)
                      .withPhoneNumber("+34111111111")

Digits.authenticate(authConfigBuilder.build());

Provide the Country Code

Digits allows you to provide just the country code field if there’s a default country that makes sense for your app. By default, the country picker uses the user’s locale in determining which country to use. This can be changed by launching Digits with authenticate(AuthConfig authConfig) and including only the country code for the phoneNumber parameter.

AuthConfig.Builder authConfigBuilder = new AuthConfig.Builder()
                      .withAuthCallBack(authCallback)
                      .withPhoneNumber("+34")

Digits.authenticate(authConfigBuilder.build());

Prefill the User’s Phone Number

This is an optional feature. Adding the permission below, in the AndroidManifest.xml, allows Digits to prefill the phone number therefore making the login process easier.

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

Note

This configuration makes it possible to read a phone number from the SIM card, but availability of the phone number is carrier- and device-specific, so the phone number may be undefined, eg http://stackoverflow.com/a/11380295/1971682.

Access Email Addresses

Digits can be configured to collect the user’s email address as an additional step after a successful phone number authentication.

To collect the user’s email, launch Digits using authenticate(AuthCallback callback, int themeResId, String phoneNumber, boolean emailCollection), optionally setting the theme ID and phone number, and setting emailCollection to true:

AuthConfig.Builder authConfigBuilder = new AuthConfig.Builder()
                      .withAuthCallBack(callback)
                      .withPhoneNumber("+34111111111")
                      .withEmailCollection();

Digits.authenticate(authConfigBuilder.build());

Email Verification

The user’s email address is now available as an Email object on the DigitsSession object returned in the authentication callback. The Email object contains a String including the email address and a boolean field specifying whether or not the email address is verified. Check out the address and verified properties.

After the user submits their email through the Activity that prompts them to do so, they will receive an email from Digits asking to confirm their email address. You can subscribe to updates about whether the email address is verified using the the SessionListener and also from your backend via the OAuth Echo endpoint.

Configure SMS Confirmation Message

After a user enters their phone number they receive an SMS containing a six digit numeric code. This code allows the user to confirm their identity.

The default SMS text is:

Enter code: 123456 into your app. (Digits by Twitter)

Your can show your app’s name in the SMS by configuring the name property in your Fabric Digits dashboard. With the name set, the SMS text appears as:

Enter code: 123456 into My Awesome App Name. (Digits by Twitter)

Note

If you’re using Twitter API keys for an existing app generated on apps.twitter.com, set the app’s name through the apps.twitter.com dashboard.

Automate Reading the SMS Pin

This is an optional feature. Adding the permission below, in the AndroidManifest.xml, allows Digits to read the SMS pin therefore making the login process easier.

<uses-permission android:name="android.permission.RECEIVE_SMS"/>

Phone Number Changes

Digits users can change their phone number through Digits. Fear not! Digits manages your entire user lifecycle. You can subscribe to receive notifications when phone number changes.

Set Up SessionListener

Implement the :code:SessionListener to receive notifications when the current user, token and secret, or phone number has changed. Add this listener instance to :code:Digits.

Developers should remove that listener when it is not needed anymore. When the SessionListener instance is tied to an Activity, it must be removed from Digits before the Activity is destroyed, otherwise it will provoke a memory leak.

//DigitsMainActivity.java
@Override
protected void onCreate() {
    sessionListener = new SessionListener() {
        @Override
        public void changed(DigitsSession newSession) {
            Toast.makeText(DigitsMainActivity.this, "Session phone was changed: " + newSession
                    .getPhoneNumber(), Toast.LENGTH_SHORT).show();
        }
    };
    Digits.addSessionListener(sessionListener);
}


@Override
protected void onStop() {
    Digits.removeSessionListener(sessionListener);
    super.onStop();
}

Detect Cancellation

Digits calls your AuthCallback.failure method if the user backs out of the authentication flow.