Send and Receive Firebase Invites from Your Android App

Before you begin

1. If you haven't yet connected your app to your Firebase project, do so from the Firebase console.
2. If you haven't yet enabled Firebase Dynamic Links, do so from the Firebase console by opening the Dynamic Links section and accepting the terms of service if prompted. Because Firebase Invites is built on Firebase Dynamic Links, you must enable Firebase Dynamic Links to use Firebase Invites.
3. Add Firebase to your Android project.
4. Add the dependency for Firebase Invites to your app-level build.gradle file:

   compile 'com.google.firebase:firebase-invites:9.6.1'
   

Send invitations

Start by building an Intent using the AppInviteInvitation.IntentBuilder class:

private void onInviteClicked() {
    Intent intent = new AppInviteInvitation.IntentBuilder(getString(R.string.invitation_title))
            .setMessage(getString(R.string.invitation_message))
            .setDeepLink(Uri.parse(getString(R.string.invitation_deep_link)))
            .setCustomImage(Uri.parse(getString(R.string.invitation_custom_image)))
            .setCallToActionText(getString(R.string.invitation_cta))
            .build();
    startActivityForResult(intent, REQUEST_INVITE);
}

Customize the invitation

When you build the invitation Intent, you must specify the title of the invitation dialog and the invitation message to send. You can also customize the image and deep link URL that get sent in the invitation, as in the example above, and you can specify HTML to send rich email invitations, which is recommended. See Firebase Invites: Best Practices.

If you have an iOS version of your app and you want to send an invitation that can be opened on iOS in addition to Android, pass the OAuth 2.0 client ID of your iOS app to setOtherPlatformsTargetApplication when you build the app invitation intent. You can find your iOS app's client ID in the GoogleService-Info.plist file you downloaded from the Firebase console. For example:

Intent intent = new AppInviteInvitation.IntentBuilder(getString(R.string.invitation_title))
    ...
    .setOtherPlatformsTargetApplication(
        AppInviteInvitation.IntentBuilder.PlatformMode.PROJECT_PLATFORM_IOS,
        getString(IOS_APP_CLIENT_ID))
    ...
    .build();

Launching the AppInviteInvitation intent opens the contact chooser where the user selects the contacts to invite. Invites are sent via email or SMS. After the user chooses contacts and sends the invite, your app receives a callback to onActivityResult:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    Log.d(TAG, "onActivityResult: requestCode=" + requestCode + ", resultCode=" + resultCode);

    if (requestCode == REQUEST_INVITE) {
        if (resultCode == RESULT_OK) {
            // Get the invitation IDs of all sent messages
            String[] ids = AppInviteInvitation.getInvitationIds(resultCode, data);
            for (String id : ids) {
                Log.d(TAG, "onActivityResult: sent invitation " + id);
            }
        } else {
            // Sending failed or it was canceled, show failure message to the user
            // ...
        }
    }
}
    

Receive invitations

When a user receives an invitation, if the user has not yet installed the app, they can choose to install the app from the Google Play Store. Then, after the app is installed, or if the app was already installed, the app starts and receives the URL to its content, if you sent one. To receive the URL to your app's content, call the getInvitation method:

@Override
protected void onCreate(Bundle savedInstanceState) {
    // ...

    // Create an auto-managed GoogleApiClient with access to App Invites.
    mGoogleApiClient = new GoogleApiClient.Builder(this)
            .addApi(AppInvite.API)
            .enableAutoManage(this, this)
            .build();

    // Check for App Invite invitations and launch deep-link activity if possible.
    // Requires that an Activity is registered in AndroidManifest.xml to handle
    // deep-link URLs.
    boolean autoLaunchDeepLink = true;
    AppInvite.AppInviteApi.getInvitation(mGoogleApiClient, this, autoLaunchDeepLink)
            .setResultCallback(
                    new ResultCallback<AppInviteInvitationResult>() {
                        @Override
                        public void onResult(AppInviteInvitationResult result) {
                            Log.d(TAG, "getInvitation:onResult:" + result.getStatus());
                            if (result.getStatus().isSuccess()) {
                                // Extract information from the intent
                                Intent intent = result.getInvitationIntent();
                                String deepLink = AppInviteReferral.getDeepLink(intent);
                                String invitationId = AppInviteReferral.getInvitationId(intent);

                                // Because autoLaunchDeepLink = true we don't have to do anything
                                // here, but we could set that to false and manually choose
                                // an Activity to launch to handle the deep link here.
                                // ...
                            }
                        }
                    });
}
    

If the launchDeepLink parameter is true, the app automatically relaunches with the URL to your app's content, which your app can handle normally. If the launchDeepLink parameter is false, you can manually start the intent returned by getInvitationIntent to handle the URL when appropriate.

You must call getInvitation() in every activity that might be launched by the link, even though the link might be available from the intent using getIntent().getData(). Calling getInvitation() retrieves the link and invitation ID, and clears that data so it is only processed once by your app.

You normally call getInvitation() in the main activity as well as any activities launched by intent filters that match the link.