View source for Firebase Invites

<table border="0" cellspacing="0" width="100%"><tr>
<td width="20%">[[Creating, Receiving and Testing a Firebase Dynamic Link|Previous]]<td align="center">[[Firebase Essentials - Android Edition|Table of Contents]]<td width="20%" align="right">[[Firebase App Indexing|Next]]</td>
<tr>
<td width="20%">Creating, Receiving and Testing a Firebase Dynamic Link<td align="center"><td width="20%" align="right">Firebase App Indexing</td>
</table>
<hr>


<htmlet>firebase_android</htmlet>


Firebase Invites provide a way for users to recommend your app to other potential users. From the point of view of the developer, invite support can be added to an app with just a few lines of code. When the user chooses to refer your app to someone else, Firebase handles all aspects of the invitation process, including presenting an invitation dialog from which recipients may be selected and transmitting the messages to the chosen recipients. 

The invitation takes the form of an email or SMS message containing a Firebase Dynamic Link URL which, when clicked, takes the user to the page within the Google Play store from which the app can be installed. Once the app has been installed, the dynamic link is passed to the app when it is launched, allowing custom behavior to be implemented using the steps outlined in the previous chapters.

== Creating a Firebase Invite Intent ==

Firebase Invites are sent using the AppInviteInvitation intent which is used to launch the app invitation activity containing the invitation dialog. 

The AppInviteInvitation intent is created and configured using the AppInviteInvitation intent builder and then launched using the startActivityForResult() method. In the following example, a basic intent consisting of a message and a deep link is created and then used to launch the invitation activity:

<pre>
public void sendInvite(View view) {
    Intent intent = new AppInviteInvitation.IntentBuilder("My Invitation")
            .setMessage("Try out this amazing app!")
            .setDeepLink(Uri.parse("http://www.example.com/invite"))
            .build();
    startActivityForResult(intent, INVITE_REQUEST);
}
</pre>

A number of methods are available for customizing the intent including the following:

•	'''setMessage()''' – Used to declare a default message to be included with the invitation. This default text can be modified by the user within the invitation dialog before the message is sent.

•	'''setDeepLink()''' – The deep link URL which is to be embedded into the dynamic link sent with the message. This can be used to pass information to the app when it is installed and launched by the message recipient.

•	'''setCustomImage()''' – Allows an image to be included within the message. The image can be up to 4000x4000 pixels in size, though 600x600 pixels is the recommended size.

•	'''setCallToActionText()''' – The text that is to appear on the Install button included within email messages. Text is limited to 32 characters.

•	'''setEmailHtmlContent()''' – Allows HTML content to be defined for email based invitations. The dynamic link URL should be substituted by the %%APPINVITE_LINK_PLACEHOLDER%% string. This method must be used in conjunction with the setEmailSubject() method. When using HTML content, the setMessage(), setCustomImage() and setCallToActionText() methods are redundant.

•	'''setEmailSubject()''' – Used to set the email subject line when using HTML content.

•	'''setGoogleAnalyticsTrackingId()''' – Allows a Google Analytics tracking ID to be specified to track the performance of the invitation.

The following code fragment shows an example invitation that makes use of HTML content:

<pre>
public void sendInvite(View view) {
    Intent intent = new AppInviteInvitation.IntentBuilder("My Invitation")
            .setDeepLink(Uri.parse("http://www.example.com/invite"))
            .setEmailSubject("I recommend this app")
            .setEmailHtmlContent("<body><p>I've been using this app." +
                    ".<p>You should try it. " +
                    "You can use this " +
                    "<a href=\"%%APPINVITE_LINK_PLACEHOLDER%%\">link</a>" +
                    " to install it on your Android device.</p></body>")
            .build();
    startActivityForResult(intent, INVITE_REQUEST);
}
</pre>
<htmlet>firebase_android</htmlet>
== Sending the Invitation ==

When the intent activity starts, the invitation dialog will appear populated with any settings configured in the intent together with a list of known contacts from which to select recipients. Additional contacts may be added by clicking on the Add recipients link and entering additional email addresses or phone numbers.

If the invitation is HTML based, the message can be previewed using the Preview Email button. Once the message is ready to send, the user simply taps on the send button in the top right-hand corner:


[[File:invites_message_window.png]]

Figure 47‑1

== Handling the Activity Result ==

Since the app invitation intent is launched using the startActivityForResult() method, clearly some code needs to be added to handle the result. This is handled in the usual way by implementing an onActivityResult() method. 

When invitations have been sent each one is automatically assigned an invitation ID which can be extracted from the results data as shown in the following method:

<pre>
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);

    if (requestCode == INVITE_REQUEST) {
        if (resultCode == RESULT_OK) {
            String[] ids = AppInviteInvitation.getInvitationIds(
				resultCode, data);
            for (String id : ids) {
                Log.d(TAG, "id of sent invitation: " + id);
            }
        } else {
            // Failed to send invitations
        }
    }
}
</pre>

== Testing Invitations ==

If invitations are being added to an app that is not yet in the Google Play store, it is only possible to test the implementation up until the point that the invitation link is clicked. At this point the Google Play store will report that the URL is not valid. If the app is already available on the store, invitations can be tested fully, including installing and launching the app and handling the deep link during app initialization using the techniques outlined in the previous chapters.

== Summary ==

App Referrals are built on Firebase Dynamic Links and provide a way for users to invite others to download and install an app with minimal coding effort on the part of the developer. All that is required is that the app configures and launches an AppInviteInvitation Intent. The Intent then handles all aspects of building the link and allowing the user to select recipients and sending method (email or SMS). If required, standard dynamic link handling can be built into the app to perform specific actions in response to a new user installing and signing into an app from an app referral.


<htmlet>firebase_android</htmlet>


<hr>
<table border="0" cellspacing="0" width="100%"><tr>
<td width="20%">[[Creating, Receiving and Testing a Firebase Dynamic Link|Previous]]<td align="center">[[Firebase Essentials - Android Edition|Table of Contents]]<td width="20%" align="right">[[Firebase App Indexing|Next]]</td>
<tr>
<td width="20%">Creating, Receiving and Testing a Firebase Dynamic Link<td align="center"><td width="20%" align="right">Firebase App Indexing</td>
</table>