Upsight logo Back to top

Push

Prerequisites


GCM Project Number and API Key

To obtain a Google Cloud Messaging (GCM) API key and Sender ID, you will have to create a Firebase project with Google.

  1. Visit the Google Firebase console and Create a New Project [or select an exisiting project] and follow the steps.

    Create Project

    Note It is not necessary to add the google-services.json file to your Android app module root directory to integrate Upsight Push notifications.

  2. Once you have created a new Android application, at the top left of the page select the Gear and go to Project Settings.

    Project Settings

  3. From the top, select Cloud Messaging tab, and save the Legacy Server key and Sender ID under Project credentials. GCM Key

  4. Save the two important pieces of information:

    • Legacy Server Key – will be used as a Google Cloud Messaging (GCM) API key, used in the Upsight Dashboard

    • Sender ID – will be used as a GCM Sender ID, used in the Android Manifest

  5. Use the Server key in your Upsight Dashboard, and your Sender ID when you configure your application.

More information on how to use the Server key in the Upsight Dashboard here.

Google Push Services Module


Integration with Push is simple. To use the Google Push Services extension, add the following in your application Manifest:

<permission
    android:name="APPLICATION_PACKAGE_NAME.permission.C2D_MESSAGE"
    android:protectionLevel="signature" />

<!-- e.g. android:name="com.yourCompany.yourApplication.permission.C2D_MESSAGE" -->
<uses-permission android:name="APPLICATION_PACKAGE_NAME.permission.C2D_MESSAGE" />
<application>

    <!-- e.g. android:value="com.yourCompany.yourApplication.0123456789" -->
    <meta-data
        android:name="com.upsight.gcm"
        android:value="APPLICATION_PACKAGE_NAME.GCM_SENDER_ID" />
    <receiver
        android:name="com.upsight.android.googlepushservices.internal.PushBroadcastReceiver"
        android:permission="com.google.android.c2dm.permission.SEND">
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />

            <!-- e.g. android:name="com.yourCompany.yourApplication" -->
            <category android:name="APPLICATION_PACKAGE_NAME" />
        </intent-filter>
    </receiver>
</application>

Applications build for Oreo and later (API level 26 and above) running on Oreo will now use notification channels. By default, the SDK will create a channel with channel id com.upsight.push_channel.default with channel name Announcements. This name can be changed by adding a meta-data key com.upsight.push_channel.default.name into your manifest for example:

        <meta-data
            android:name="com.upsight.push_channel.default.name"
            android:value="Upsight Example Channel Name" />

If you would like to display marketing content delivered via a push message, create an UpsightPushBillboard in your launch Activity's onResume() and call billboard.destroy() in the onPause():

UpsightBillboard.Handler handler = UpsightBillboardHandlers.forDefault(activity);
UpsightBillboard billboard = UpsightPushBillboard.create(mUpsight, handler);

Tip: The permission requirements android.permission.INTERNET, android.permission.GET_ACCOUNTS, android.permission.WAKE_LOCK, and com.google.android.c2dm.permission.RECEIVE are automatically merged to your application Manifest.

Handling a Push to a Custom URI


Sending a Push from the Upsight Dashboard allows you to direct a user to a custom URI. A custom URI can be an arbitrary URI like a browser URL, Google Play URI, or deep-link for Facebook. A custom URI can also allow you to execute specific behaviour based on your URI parameters. If you send a URI that the device cannot handle because there is no registered Intent Filter, an error message will be logged to ADB, but no notification will be shown.

If you wish to handle a custom URI within your app, you will need to declare an Intent Filter on an Activity in your Manifest. The following is an example of an application handling an Intent from a Push Notification with a custom URI.

<application>

    <!-- e.g. android:name="com.yourCompany.yourApplication.YourActivity" -->
    <activity android:name=".ACTIVITY_NAME">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />

            <!-- e.g. android:host="my_host" -->
            <!-- e.g. android:scheme="my_scheme" -->
            <data
                android:host="HOST"
                android:scheme="SCHEME" />
        </intent-filter>
    </activity>
</application>

To have this Activity open when the user clicks your Push Notification, send a Push from the Upsight Dashboard with URL or URI selected as your action and with the following URI:

my_scheme://my_host/

Customizing Push Notification Icons


You may optionally customize the appearance of Push Notifications by providing a customized NotificationCompat.Builder:

public class MyNotificationBuilderFactory implements UpsightPushNotificationBuilderFactory {

    @Override
    public NotificationCompat.Builder getNotificationBuilder(UpsightContext upsight, String title, String message, String imageUrl, String channelId, int priority) {
        int iconResId = R.drawable.my_push_icon;                 // Customize icon.
        String customTitle = String.format("Hey Jo, %s", title); // Customize title.

        return new NotificationCompat.Builder(upsight.getApplicationContext(), channelId)
                .setPriority(priority)
                .setSmallIcon(iconResId)
                .setStyle(new NotificationCompat.BigTextStyle().bigText(message))
                .setContentTitle(customTitle)
                .setContentText(message);
    }
}

Then declare your UpsightPushNotificationBuilderFactory implementation in the application Manifest:

<!-- e.g. android:value="com.yourCompany.yourApplication.MyNotificationBuilderFactory" -->
<meta-data
    android:name="com.upsight.notification_builder_factory"
    android:value="FULL_CLASS_PATH_TO_YOUR_UPSIGHT_NOTIFICATION_BUILDER_FACTORY_IMPLEMENTATION" />