App Service Mobile Apps completed quickstart for Xamarin.Android apps

This repository contains an Xamarin.Android app project based on the App Service Mobile Apps quickstart project, which you can download from the Azure portal. These projects have been enhanced by the addition of offline sync, authentication, and push notification functionality. This demonstrates how to best integrate the various Mobile Apps features. To learn how to download the Xamarin.Android quickstart app project from the portal, see Create an Xamarin.Android app. This readme topic contains the following information to help you run the sample app project and to better understand the design decisions.

• Overview
• Configure the Mobile App backend
• Configure the Xamarin.Android app
  • Set the Mobile App backend URL
  • Configure authentication
  • Configure push notifications
• Running the app
• Implementation notes
  • Push to an authenticated user
  • Client-added push notification tags
  • Authenticate first

##Overview The projects in this repository are equivalent to downloading the quickstart Xamarin.Android app project from the portal and then completing the following Mobile Apps tutorials:

• Enable offline sync for your Xamarin.Android app
• Add authentication to your Xamarin.Android app
• Add push notifications to your Xamarin.Android app

Configure the Mobile App backend

Before you can use this sample, you must have created and published a Mobile App backend project that supports both authentication and push notifications (the backend supports offline sync by default). You can do this either by completing the previously indicated tutorials, or you can use one of the following Mobile Apps backend projects:

• .NET backend quickstart project for Mobile Apps
• Node.js backend quickstart project for Mobile Apps

The readme file in this project will direct you to create a new Mobile App backend in App Service, then download, modify, and publish project to App Service.

After you have your new Mobile App backend running, you can configure this project to connect to that new backend.

Configure the Xamarin.Android app

The app project has offline sync support enabled, along with authentication and push notifications. However, you need to configure the project, including authentication and push notifications, before the app will run properly.

Set the Mobile App backend URL

The first thing you need to do is to set the URL of your Mobile App backend in the MobileServiceClient constructor. To do this, open the ToDoActivity.cs project file, locate the applicationURL constant and replace the URL with the URL of your Mobile App backend.

Configure authentication

Because both the client and backend are configured to use authentication, you must define an authentication provider for your app and register it with your Mobile App backend in the portal.

1. Follow the instructions in the topic to configure the Mobile App backend to use one of the following authentication providers:

   • AAD
   • Facebook
   • Google
   • Microsoft account
   • Twitter

2. By default, the app is configured to use server-directed Facebook authentication. To use a different authentication provider, change the provider by changing the value of the provider constant in ToDoActivity.cs and changing it to one of these other values: AAD, Google, MicrosoftAccount, or Twitter.

Configure push notifications

You need to configure push notifications by registering your Xamarin.Android app for Google Cloud Messaging (GCM) in the Google developer console, and then storing the API key in Azure. This key is used by Azure to connect to GCM to send push notifications. Assuming that you have already created the notification hub in your backend as instructed in the server project readme, complete the following sections of the push notifications tutorial to configure push notifications:

2. Register your app for push notifications.
3. Configure the backend to send push notifications.

Finally, open the ToDoBroadcastReceiver.cs project file and set your Google project number in the senderIDs variable

public class ToDoBroadcastReceiver : GcmBroadcastReceiverBase<PushHandlerService>
{
    // Set the Google app ID.
    public static string[] senderIDs = new string[] { "MY_PROJECT_NUMBER" }; 
}

Running the app

With both the Mobile App backend and the app configured, you can run the app project.

1. In the Android emulator or device, make sure you have a valid Google account added.

2. Run the app, click the Sign-in button and authenticate with the provider.

   After authentication succeeds, the device is registered for push notifications and any existing data is downloaded from Azure.

3. Type text in Insert a TodoItem, and then click Save.

   Note that after the insert completes, the app receive a push notification from GCM. The notification is displayed in the notification bar when the app isn't running. Clicking the notification launches the app.

Implementation notes

This section highlights changes made to the original tutorial samples and other design decisions were made when implementing all of the features or Mobile Apps in the same client app.

###Push to an authenticated user Because the user is authenticated before push registration occurs, the user ID is automatically added as a tag in the installation. The backend then uses this tag to send push notifications only to devices registered to the user doing the insert. For more information, see the readme file for the quickstart completed backend project.

###Client-added push notification tags

When a mobile app registers for push notifications using a Mobile Apps backend, there are two default tags that can get added to the registration in Azure Notification Hubs: the installation ID, which is unique to the app on a given device, and the user ID, which is only added when the user has been previously authenticated. Any other tags that get supplied by the client are ignored, which is by design. (Note that this differs from Mobile Services, where the client could supply any tag and there were hooks into the registration process on the backend to validate tags on incoming registrations.)

Because the client can’t add tags and at the same time there is not service-side hooks into the push notification registration process, the client needs to do the work of adding new tags to a given registration. In this sample, an /updatetags endpoint in the backend lets the client add tags to their push registration. The client calls that endpoint to create new tags, as you can see in the following:

try
{
    // Define two new tags as a JSON array.
    var body = new JArray();
    body.Add("broadcast");
    body.Add("test");

    // Call the custom API '/api/updatetags/<installationid>' 
    // with the JArray of tags.
    var response = await client
        .InvokeApiAsync("updatetags/"
        + client.InstallationId, body);
}
catch (MobileServiceInvalidOperationException ex)
{
    System.Diagnostics.Debug.WriteLine(
        string.Format("Error with Azure push registration: {0}", ex.Message));
}

For more information, see Adding push notification tags from an Azure Mobile Apps client.

###Authenticate first This sample is a little different from the tutorials in that push notifications are send to all devices with push registrations that belong to a specific user. When an authenticated user registers for push notifications, a tag with the user ID is automatically added. Because of this, it's important to have the user sign-in before registering for push notifications. You should also have the user sign-in before executing any data or sync requests, which will result in an exception when the endpoint requires authentication. You also probably don't want an unauthenticated user to see offline data stored on the device. The following button event handler shows how to require explicit user sign-in before push registration and doing the initial data sync:

[Java.Interop.Export()]
public async void LoginUser(View view)
{
    // Only register for push notifications and load data after authentication succeeds.
    if (await Authenticate())
    {
        // Register the app for push notifications.
        GcmClient.Register(this, ToDoBroadcastReceiver.senderIDs);

        //Hide the button after authentication succeeds. 
        FindViewById<Button>(Resource.Id.buttonLoginUser).Visibility = ViewStates.Gone;

        // Load the data.
        OnRefreshItemsSelected();
    }
}