Oracle Help Center | Oracle Push Cloud Service (Standalone) title

Step-by-Step Setup Instructions

This topic provides detailed instructions for integrating your Android mobile app with Oracle Push Cloud Service.

Before You Continue

Step 1: Set Up an Android Platform for Your App

[1.1] Locate your project's cloud messaging credentials.

[1.2] Configure Oracle Push Cloud Service for your app using the Web Dashboard.

From the Web Dashboard, click Add Platform, and then click Android.

"Add Platform page on Oracle Push Cloud Service Web Dashboard"

Enter your project's FCM or GCM credentials (as described in Getting Your Project's FCM Credentials) on the Android platform dialog.

FCM Credentials GCM Credential
"Google project number" field: Sender ID Google Project Number
"Google API key" field: Server Key Google API Key

These values enable Oracle Push Cloud Service to target your application through the cloud messaging platform.

"Android app configuration on Oracle Push Cloud Service Web Dashboard"

Step 2: SDK Installation - Obtain Necessary Files and Add Them to Your Project

Once you have entered your project's FCM or GCM Credentials, Oracle Push Cloud Service generates a pushio_config.json file for you to include in your application. This JSON file is packaged with your FCM or GCM Credentials, depending on what you entered for your project. Oracle Push Cloud Service uses the cloud messaging credentials to target your application properly. Your application must also include the PushIO Manager for Android SDK library from GitHub.

[2.1] Before you obtain the SDK files, verify that the folders in Android Studio to contain them are present. Open your app project in Android Studio, and then select the Project view of your project. Expand the folder that shows your project name, and then expand the app folder.

"Android Studio project files setup for PushIOManager"

[2.2] From the Web Dashboard's Android page for your app, click Download the pushio_config.json for Android to download the file. Include the file in your project's assets folder:

"Android project file download page"

[2.3] To download the SDK library, click the Download PushIO Manager for Android from GitHub download.

Add the PushIOManager.aar file from the download to your project's libs folder.

Tip: Right-click the directory folder in the Project Files tab, and select Show in Explorer (or Reveal in Finder if you are using iOS). This action opens the directory in a file system window, and then you can drag-and-drop the file into the desired folder.

"Adding PushIOManager to libs folder"

[2.4] You must also add support v4 and Google Play Services libraries as dependencies in your project, as described in the next section. Before proceeding further, make sure you have downloaded the Android Support Library and Google Play services library using the Android SDK Manager.

Step 3: Adding Dependencies Using Android Studio

In this section, you'll update your project's build.gradle files. Android Studio projects contain a project-level build.gradle file (contained in the project's top-level folder, typically project-name/build.gradle) and a module level build.gradle file (contained in the project's app folder, typically project-name/app/build.gradle). Ensure that you edit the correct file in the following steps.

NOTE: The information in this section assumes that you are using Android Studio for your project. The Android development team ended development and official support for Android Developer Tools (ADT) in Eclipse in December 2015. Please refer to the Migrate to Android Studio document for information about migrating from Eclipse to Android Studio.

[3.1] Open your project-level build.gradle file and add the following build rules under the allprojects > repositories section, below the existing jcenter() content:

    flatDir {
        dirs 'libs'
    }

[3.2] In your project-level build.gradle file, verify that your minSdkVersion is set to 14 (Android SDK version of 14, "Ice Cream Sandwich") or higher.

    android {
        defaultConfig {
            minSdkVersion 14
       }
    }

[3.3] Open your module's build.gradle file and add the following build rules to the dependencies section, below the existing contents:

    compile(name: 'PushIOManager', ext: 'aar')
    compile 'com.android.support:support-v4:25.1.1'  
    compile 'com.google.android.gms:play-services-location:10.2.0'
    compile 'com.google.android.gms:play-services-gcm:10.2.0'  

NOTE: Because of a 65k limit on the number of method references, Google recommends that you include only the specific Google Play services APIs that your app uses, instead of the entire package. Instructions for selectively including Google Play services APIs are available here.

[3.4] Sync the project with the updated Gradle file.

Step 4: Integrate the Android Push IO Manager

[4.1] In your AndroidManifest.xml file (typically located in the project-name/app/src/main folder), the following user-permissions are required to use Google Cloud Messaging. Put them inside the <manifest> element, above the <application> element. Note that ${applicationId} will be substituted with the value of the package attribute in the manifest element; that is, your app and package name.

    <uses-permission android:name="${applicationId}.permission.C2D_MESSAGE" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.INTERNET"/>

    <!-- Optional permission -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <permission android:name="${applicationId}.permission.C2D_MESSAGE" android:protectionLevel="signature" />

    <!-- Permission for PUSHIO_MESSAGE -->
    <permission android:name="${applicationId}.permission.PUSHIO_MESSAGE" android:protectionLevel="signature"/>
    <uses-permission android:name="${applicationId}.permission.PUSHIO_MESSAGE"/>

[4.2] In your AndroidManifest.xml file, make the following two changes:

1) Set up the PushIOBroadcastReceiver by adding the following lines inside the <application> element, below the main activity element.

    <receiver android:name="com.pushio.manager.PushIOBroadcastReceiver"
        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="${applicationId}" />
        </intent-filter>
    </receiver>

    <activity android:name="com.pushio.manager.PushIOActivityLauncher" android:exported="true" />
    <service android:name="com.pushio.manager.PushIOGCMIntentService" />
    <service android:name="com.pushio.manager.PushIOEngagementService" />

NOTE: In the PushIOActivityLauncher declaration, we include android:exported="true" for backward compatibility. Even though Google has moved from C2DM, the permissions still use the C2DM name for backwards compatibility with older devices. If you are using Android API 4.4 or earlier, remove the attribute android:exported="true" from the declaration of PushIOActivityLauncher.

2) To ensure that PushIO SDK is able to correctly receive GCM/FCM push notifications, declare the following services. Add the following lines inside the <application> element, below the lines you just added to set up the PushIOBroadcastReceiver.

    <service android:name="com.pushio.manager.PIOGCMRegistrationIntentService"
            android:exported="false"/>
    <service
            android:name="com.pushio.manager.PIOInstanceIDListenerService"
            android:exported="false">
      <intent-filter>
           <action android:name="com.google.android.gms.iid.InstanceID" />
      </intent-filter>
    </service>

[4.3] In your main Activity class, import the PushIOManager library by adding the following line below the other import statements. (Your main Activity class is typically located in project-name/app/src/main/java/package-name. If you have not renamed the class from the Android project default, it is called MainActivity.java.)

    import com.pushio.manager.PushIOManager;

[4.4] In your main Activity class, override the onStart() method if it is not already present, and then call PushIOManager.ensureRegistration() from it. This ensures that registration is maintained between all application restarts.

    // Instantiate the Push IO Manager
    // Ensure that any registration changes with Google get reflected with Push IO.
    // Also registers for Broadcast Push Notifications (All Users).
    PushIOManager.getInstance(this).ensureRegistration();

Ready, Set, Push!

This completes the basic Android SDK setup. Once you have built your application and have installed it on a test device or emulator on which Google Play services are installed and updated, you can test your integration.

[1] Log into the Web Dashboard.

[2] Navigate to the Push tab.

[3] From the Audience drop-down menu, choose All Active Devices.

[4] Type in a message and click Send Now.

You should see your first true Android push notification.

The next step provides optional instructions for customizing how your app handles incoming push messages and listens for notification-tap broadcasts.

Optional - Customize Incoming Push Messages and Notification Taps

[1] Customize how push messages are handled.

On Android, Oracle Push Cloud Service broadcasts push notifications using the action ${applicationId}.PUSHIOPUSH. If you don't choose to have your app handle this broadcast, the Oracle Push Cloud Service will create a standard notification for you, using the badge name and sound name to gather the proper resources from your application assets.

If you choose to customize notifications, you must do both of the following:

IMPORTANT: Make sure to add attribute android:exported with value as false to the broadcast receiver.

From this broadcast receiver, you can direct the push anywhere you would like. A common practice is to create an IntentService that creates the notification. It is important that this BroadcastReceiver notifies PushIOManager that it is handling the notification using setResultExtras(), so that PushIOManager doesn’t create a duplicate notification.

public void onReceive(Context context, Intent intent) {
    CustomNotificationService.runIntentInService(context, intent);
    Bundle extras = getResultExtras(true);
    extras.putInt(PushIOManager.PUSH_STATUS, PushIOManager.PUSH_HANDLED_NOTIFICATION);
    setResultExtras(extras);
}

Tip: Use the PushIOActivityLauncher for the PendingIntent of your notifications. Using this class will automatically handle push engagement tracking for you. The PushIOActivityLauncher expects you to pass the notification intent as extras from the broadcast receivers.

Intent newIntent = new Intent(this, PushIOActivityLauncher.class);
newIntent.putExtras(intent);
PendingIntent lPendingIntent = PendingIntent.getActivity(this, 0, newIntent, PendingIntent.FLAG_UPDATE_CURRENT);

To handle an incoming push while your app is running, register a broadcast receiver on the onResume() of your activity, and unregister the receiver on the activity's onPause(). The following example creates a local broadcast receiver, handles the push, and tells PushIOManager that the push was handled “in-app”. This will automatically track the in-app engagement and prevent PushIOManager from creating a custom notification. this.abortBroadcast() is used to stop the broadcast from hitting the application-wide NotificationBroadcastReceiver that we created earlier.

private BroadcastReceiver mBroadcastReceiver;
.
.
.
@Override
public void onResume(){
    mBroadcastReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            Bundle extras = getResultExtras(true);
            extras.putInt(PushIOManager.PUSH_STATUS, PushIOManager.PUSH_HANDLED_IN_APP);
            setResultExtras(extras);
            this.abortBroadcast();

            // Your code to handle the push notification.

        }
    };
    registerReceiver( mBroadcastReceiver, new IntentFilter("${applicationId}.PUSHIOPUSH") );
}

In onPause(), call unregisterReceiver() to stop listening for incoming push when this activity closes. When this activity is in background/not visible, the incoming push will be directed to the application-wide NotificationBroadcastReceiver that we declared in <manifest> earlier.

@Override
public void onPause(){
    super.onPause();

    unregisterReceiver(mBroadcastReceiver);
}

[2] Customize how notification taps are handled.

To intercept notification-pressed broadcasts, add the following Oracle Push Marketing Cloud permissions in the Android Manifest under <manifest>. This is the same permission that you added in the earlier section to handle incoming push.

<permission android:name="${applicationId}.permission.PUSHIO_MESSAGE"
    android:protectionLevel="signature"/>
<uses-permission android:name="${applicationId}.permission.PUSHIO_MESSAGE"/>

When a notification is pressed and if its PendingIntent points to PushIOActivityLauncher, an intent is broadcast for the action ${applicationId}.NOTIFICATIONPRESSED. To handle this action, you need to register an <intent-filter> in your AndroidManifest.xml.

<activity android:name="${applicationId}.myactivity">
    <intent-filter>
        <action android:name="${applicationId}.NOTIFICATIONPRESSED"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

What's Next?

Now that you have completed the basic configuration and have tested push notifications, we recommend that you continue to the following topics to add Oracle Push Cloud Service features to your app:

Also, see our Android FAQ for troubleshooting information and answers to general questions about PushIO SDK for Android.