Android Push Guide

Prerequisites


GCM Project Number and API Key

To obtain a Google Cloud Messaging (GCM) Project number and API Key, you will have to create a Google APIs Project.

  1. Visit the Google APIs Console and create (or select an existing) project.

  2. Scroll down to Google Cloud Messaging for Android and turn it on.

  3. On the API Access page, click Create New Server Key.

    • Leave the input box for IP addresses blank.

    • Click Create.

  4. Save the two important pieces of information:

    • The API Key – copy the API Key you just created.

    • The Project Number – This should be visible on the Overview page as Project Number.

  5. Use the API key in your Upsight Dashboard, and your Project Number when you configure your application. More information here.

Handling and Integrating Push


GCM Push Registration

In order to enable you to opt out of Opens, we have simplified the process of registering or deregistering a GCM push notification by decoupling the open request from GCM registration.

To register or deregister a GCM push notification, use the following classes:

(new GCMRegistrationRequest()).register(context);
(new GCMRegistrationRequest()).deregister(context);

Enabling Push Notifications

In order for your app to receive Push Notifications, you will need to add the appropriate permissions to your Android manifest with your GCM Project Number and API key.

  1. Add the appropriate permissions to your Android manifest. Replace <YOUR_APP_PACKAGE_NAME> with your application's package name.

    <permission android:name="<YOUR_APP_PACKAGE_NAME>.permission.C2D_MESSAGE" android:protectionLevel="signature" />
    <uses-permission android:name="<YOUR_APP_PACKAGE_NAME>.permission.C2D_MESSAGE" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    
  2. Now add this receiver to the manifest (be sure to substitute your application's package name).

    <!-- This is needed to receive Google Cloud Messaging intents from the system. -->
    <receiver android:name="com.playhaven.android.push.GCMBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND">
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
            <category android:name="<YOUR_APP_PACKAGE_NAME>" />
        </intent-filter>
    </receiver>
    
  3. When calling PlayHaven.configure(), you will need to provide your Google Cloud Messaging project number.

    PlayHaven.configure(getApplicationContext(), token, secret, projectNumber);
    

Now your app is ready to receive push notifications.

Handling a Push to a Content Unit

If you wish to create a new content unit to send a push notification to, you need to create a placement for the content unit first. To do so, go to the Upsight Dashboard, click on the app you wish to set the Push up for, select App Settings and then select Placements. Remember, this Placement should only be used for the content units you are using for the push notification. This placement should NOT be integrated into your app.

If you are sending a push notification to an existing content unit, you do not need to create another placement for it. When a notification from Upsight results in Upsight content being displayed, it will be shown in FullScreen mode. When that is closed, your application will be launched using its default Activity. This is the same Activity that is launched from its icon in the Launcher.

You can retrieve the data from the current Intents extras like this:

Bundle adData = getIntent().getBundleExtra(PlayHavenView.BUNDLE_DATA);
if (adData != null && adData.size() > 0) {
    if(adData.containsKey(PlayHavenView.BUNDLE_DATA_REWARD)){
        // Do reward stuff.
    }

    if(adData.containsKey(PlayHavenView.BUNDLE_DATA_OPTIN)) {
        // Do opt-in data stuff.
    }

    if(adData.containsKey(PlayHavenView.VGP)) {
        // Do VGP stuff.
    }
}

Handling a Push to a Custom URI

Upsight’s Push solution allows you to pass a custom URI location to send the user to a location (e.g. your In-App Purchase store). You will need to implement a Receiver (and declare it in your Manifest) in order to handle custom URIs on your own. An example can be found in the section below.

You can also send arbitrary URIs via push notifications. Some examples would be browser URLs, Google Play URIs, and deep linking for Facebook or your own application. If you send a URI that the device cannot open, an error message will be logged to ADB, but no notification will be shown.

You will need to implement a Receiver (and declare it in your Manifest) in order to handle custom URIs on your own. The following example is of an application getting a custom number of Easter Eggs, silently, from a push notification. First, you have to add the following to the manifest:

AndroidManifest.xml
<!-- This receives a custom URI broadcast from the PlayHaven SDK. -->
<receiver android:name="com.playhaven.android.breweryblocks.CustomReceiver">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name=”android.intent.category.DEFAULT” />
        <category android:name=”android.intent.category.BROWSABLE” />
        <data android:scheme=”phdiagnostic” android:host=”com.playhaven.android.diagnostic:/>
    </intent-filter>
</receiver>

Next, you create the following class:

CustomReceiver.java
public class CustomReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        //Code to do whatever you want: open a part of the app, etc, etc.
        Log.v("BreweryBlocks", "This many eggs: " + intent.getData().getQueryParameter("easterEggs"));
    }
}

Note that one very important thing to remember about BroadcastReceiver is that it will not run in its own thread. Network requests and other long-running tasks should be handled with appropriate processes and threads to avoid ANR and other errors.

Passing Data


Any additional parameters in the query portion of the URI will be provided to the receiving application as part of the Intent Bundle. By leveraging this functionality, publishers can add parameters to the query string of the URI, and then receive those parameters when their application launches. For example, they could send:

yourappname://goToLocation?extraOption=value

This would send the string value value from the Intent Bundle for the extraOption argument when the user clicks on the notification and the goToLocation activity opens.

A great use for this feature would be to send your customers to a specific item in your in-app store.

yourappname://inAppStore?itemId=1352

Using Device Identifiers


If you are uploading a list of devices via .CSV upload from the Push dashboard, the file format has changed to be able to handle different device id types.

The new format for the .csv file is as follows:

device_id_type,identifier

Here is a .csv file example:

sid,12345
device_token,951623572134c34c

Important Be sure to adhere to the following rules:

  • Make sure you only have 1 device per line.

  • The device ID types can be device_token, sid or push_token.

Troubleshooting


Application Stopped State

An application that has been installed but never launched is in a stopped state. It is also considered to be in a stopped state if it has been force-stopped but never re-launched. Applications will not receive broadcasts (and therefore Push Notifications) while in a stopped state. Your application will only receive Push Notifications again after a call to PlayHaven.configure() where you provide a GCM project number.

Valid Google Accounts

Only devices with a valid Google account associated will receive Push Notifications from GCM, and they must have Google Play installed.

Manifest Merging Not Supported

If you see the following message, you will need to reconfigure your manifest files.

Manifest merging is not supported.

Then, you will need to copy the content from the PlayHaven/AndroidManifest.xml into your AndroidManifest.xml.

Pushes Are Not Received

If you are sending pushes and not receiving them in the notification bar, look for a line in your application logs that looks like the following:

11-13 10:42:05.270: I/ActivityManager(270): Start proc com.myorg.MyApp for broadcast com.myorg.MyApp/com.playhaven.android.push.GCMBroadcastReceiver: pid=9499 uid=10059 gids={3003, 1015, 1028}

Please check your AndroidManifest.xml file to ensure you have the following:

<receiver android:name="com.playhaven.android.push.PushReceiver">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="com.playhaven.android" />
    </intent-filter>
</receiver>