Expand Your App’s Reach with Google’s App Invites

There were some major announcements at Google I/O 2015, but there were also several exciting enhancements to Google Play Services announced that focus on increasing your app’s reach in the market. One of my favorite new features in Google Play Services has to be App Invites, which gives developers a simple way of allowing their users to share their app with friends through e-mail or SMS. App Invites also provides a way for developers to add deep link content in these invitations, enabling a unique way of bubbling up information, such as discount codes or exclusive content, to new users when your app is installed.

How App Invites Work

Traditional app discovery is usually done by browsing a large list of apps or searching for a specific keyword, but App Invites enables apps to be shared user-to-user. When people share an app invite from a mobile app, it kicks off the App Invite flow. Google Play Services handles what happens if an app is installed or not, and provides a deep link for adding additional context. Here’s what a normal flow looks like:

App Invites are currently in beta on both iOS and Android from Google.

Getting Started

For this blog post, I’ll focus on Android development (Xamarin.iOS support is coming soon). App Invites are packaged as part of Google Play Services 7.5, which are currently available as a pre-release NuGet Package. Simply search for “AppInvite” in the NuGet Package Manager in either Visual Studio or Xamarin Studio with the pre-release packages flag enabled.

The next step is to enable Google Services for your Android app. Google has a nice wizard to help you create or choose an existing app to enable services for on the Google Developer Console.

Enter your app name and Android package name:

Check App Invites and then add your Android Signing Certificate SHA-1 information. To find your SHA-1 Fingerprint, simply follow our documentation. If you’ve used Google Maps in the past, this is the same process.

After this step in the process, you may be prompted to download and copy a configuration file, however, this is not necessary for Xamarin.Android apps at this time.

Sending App Invites

I’ve decided to integrate App Invites into my app Coffee Filter, which enables you to find coffee shops based on your geolocation. Coffee Filter has a master-detail view setup, and I chose to allow users to send app invites from the coffee shops detail page, which enables me to deep link to the coffee shop in this example.

When you want to trigger the App Invite, you will need to start by creating a new Intent using the AppInviteInvitation.IntentBuilder class. The only required field is the title that is displayed to the user on the invite, but you may want to also provide a message to display and a deep link URL that you can use when receiving the app invite.

int RequestInvite = 0;
void SendInvite() 
{
  var intent = new AppInviteInvitation.IntentBuilder("Invite Friends to Coffee")
	           .SetMessage("Join me for coffee with Coffee Filter")
	           .SetDeepLink(Android.Net.Uri.Parse("http://motzcod.es/" + viewModel.Place.PlaceId))
                   .Build();

  StartActivityForResult(intent, RequestInvite);
}

//Get information back from the App Invites request
protected override void OnActivityResult (int requestCode, Result resultCode, Intent data) 
{
  base.OnActivityResult (requestCode, resultCode, data);

  if (requestCode == RequestInvite) 
  {
    if (resultCode == Result.Ok) 
    {
      //Check how many invitations were sent. You could optionally track this data as
      //the Ids will be consistent when you receive them
      var ids = AppInviteInvitation.GetInvitationIds((int)resultCode, data);
      ShowMessage("You just sent " + ids.Length + " invites!");
    } 
    else 
    {
      // Sending failed or it was canceled, show failure message to the user
      ShowMessage("No coffee invites were sent.");
    }
  }
}

As you can see, I’m deep linking to a specific coffee shop ID that I can use later when receiving the deep link. For your app, you should determine what type of deep link information you want, if any. With just this code, your users will now have the ability to send app invites out:

This will send out an e-mail with your app on a card view, enabling a one-click install of your app:

Receiving App Invites

When a user receives and accepts an app invite, the app may or may not be installed. This means you will need to handle each instance separately. If the app is already installed, you can simply handle and process the app invite in your Main Activities OnCreate method, with just a few lines of code:

protected override void OnCreate(Bundle bundle) 
{
  // No savedInstanceState, so it is the first launch of this activity
  if (bundle == null && AppInviteReferral.HasReferral(Intent)) 
  {
    // In this case the referral data is in the intent launching the MainActivity,
    // which means this user already had the app installed.
    LaunchDeepLinkActivity(Intent);
  }
}

// Process the deep link information, however if you don't have any deep links
// this may be a good time to welcome them to the application
public void LaunchDeepLinkActivity(Intent intent) 
{
  var newIntent = new Intent (intent);
  newIntent.SetClass (this, typeof(DetailsActivity));
  StartActivity(newIntent);
}

If the user doesn’t have the app installed, they will install it and then the Google Play Store will send a broadcast out notifying your app to process the deep link. You will need to create a ReferrerReceiver that will handle this broadcast:

[BroadcastReceiver(Exported = true)]
[IntentFilter(new []{"com.android.vending.INSTALL_REFERRER"})]
public class ReferrerReceiver : BroadcastReceiver 
{
  public override void OnReceive (Context context, Intent intent)
  {
    // Create deep link intent with correct action and add play store referral information
    var actionIntent = new Intent(context.GetString(Resource.String.action_deep_link))
    var deepLinkIntent = AppInviteReferral.AddPlayStoreReferrerToIntent(intent, actionIntent);
    // Let any listeners know about the change
    LocalBroadcastManager.GetInstance(context).SendBroadcast(deepLinkIntent);
  }
}

Inside of your MainActivity, you will need to register a new local broadcast receiver that will receive this broadcast and launch the deep link activity.

class InviteBroadcastReceiver : BroadcastReceiver
{
  readonly MainActivity activity;
  public InviteBroadcastReceiver(MainActivity activity)
  {
    this.activity = activity;
  }

  public override void OnReceive (Context context, Intent intent)
  {
    if (!AppInviteReferral.HasReferral (intent))
      return;

    activity.LaunchDeepLinkActivity (intent);
  }
}

You should register and unregister this broadcast receiver in the OnStart and OnStop methods of your activity.

InviteBroadcastReceiver deepLinkReceiver;
void RegisterDeepLinkReceiver() 
{
  // Create local Broadcast receiver that starts 
  //DeepLinkActivity when a deep link is found
  deepLinkReceiver = new InviteBroadcastReceiver(this);
  var intentFilter = new IntentFilter(GetString(Resource.String.action_deep_link));

  LocalBroadcastManager.GetInstance(this).RegisterReceiver(deepLinkReceiver, intentFilter);
}

void UnregisterDeepLinkReceiver() 
{
  if (deepLinkReceiver == null)
    return;

  LocalBroadcastManager.GetInstance(this).UnregisterReceiver(deepLinkReceiver);
}

protected override void OnStart ()
{
  base.OnStart ();
  RegisterDeepLinkReceiver ();
}

protected override void OnStop ()
{
  base.OnStop ();
  UnregisterDeepLinkReceiver ();
}

Finally, when your deep link activity starts, you’ll want to process the incoming intent to see if you need to handle the deep link action. In my app, I parse out the place ID that we sent earlier and refresh the data.

protected override void OnStart ()
{
  base.OnStart ();
  ProcessReferralIntent (Intent);
}

void ProcessReferralIntent(Intent intent)
{
  if (!AppInviteReferral.HasReferral (intent))
    return;

  var invitationId = AppInviteReferral.GetInvitationId (intent);
  var deepLink = AppInviteReferral.GetDeepLink (intent);
  var info = deepLink.Replace ("http://motzcod.es/", string.Empty);
  viewModel.Place.PlaceId = info;
  RefreshData ();
}

Now, when the app is launched it will go directly to the deep linked coffee shop:

Learn More

To learn more about App Invites, including tracking invitations, be sure to see the Google App Invites documentation. Additionally, you can find the entire source code for Coffee Filter with App Invites on my GitHub.

Discuss this post in the Xamarin Forums