Connecting the AppMetrica Push SDK

The Push SDK for Android is a library in the AAR format. The library is available in the Maven repository.

Since the AppMetrica Push SDK version 1.0.0, it uses the Firebase Cloud Messaging (FCM) service to send push notifications.

This section describes the steps to enable and initialize AppMetrica Push SDK:

  1. Step 1. Prepare your app
  2. Step 2. Enable the library
  3. Step 3. Initialize the library
  4. Step 4. Configuring Silent Push Notifications
  5. Step 5. (Optional) Enable push tokens update
  6. Sending additional information
  7. Detecting the application launch via push notification
  8. Setting the default icon

Step 2. Enable the library

Since version 1.4.0 to the Push SDK added the OKHttp library. The SDK uses it for caching images that are displayed in push notifications. Caching rules are taken from the cache-control HTTP header. If you do not want the images to be cached, connect the library without caching.

  1. In the build.gradle file add the following dependencies in the dependencies block:
    dependencies {
        ...
        implementation "com.yandex.android:mobmetricapushlib:1.5.1"
        implementation "com.google.firebase:firebase-messaging:19.0.1"
        implementation "com.google.android.gms:play-services-base:16.1.0"
        implementation "com.android.support:support-compat:28.0.0"
        ...
    }
    Copied to clipboard
    Note. The minimum version of support-compat is 26.0.0.
  2. Initialize Firebase using one of the following methods:

    Using Google Services Plugin
    1. Download the configuration file google-services.json and put it in the project module's directory (such as app).
    2. In order to work with the file correctly, enable the Google Services plugin in the project by adding the following lines to the build.gradle file:

      project
      buildscript{
          ...
          dependencies {
              ...
              classpath 'com.google.gms:google-services:4.3.0'
              ...
          }
          ...
      }
      Copied to clipboard
      application (module)
      // In the end of the file.
      apply plugin: 'com.google.gms.google-services'
      Copied to clipboard
    Without using the plugin

    Make changes in the application element in the AndroidManifest.xml file:

    <meta-data android:name="ymp_firebase_default_app_id" android:value="APP_ID"/>
    <meta-data android:name="ymp_gcm_default_sender_id" android:value="number:SENDER_ID"/>
    
    <!-- If you have a dependency on com.google.firebase:firebase-auth -->
    <meta-data android:name="ymp_firebase_default_api_key" android:value="API_KEY"/>
    Copied to clipboard

    APP_ID — ID of the app in Firebase. You can find it in the Firebase console: go to the Project settings. In the Your application section copy the value of the application ID field.

    SENDER_ID — The unique ID of the sender in Firebase. You can find it in the Firebase console: go to Project settings → Cloud Messaging and copy the value of the Sender ID field.

    API_KEY — App key in Firebase. You can find it in the current_key field of the google-services.json file. You can download the file in the Firebase console.

    Using with other Firebase projects

    Make changes in the application element in the AndroidManifest.xml file:

    <meta-data android:name="ymp_firebase_app_id" android:value="APP_ID"/>
    <meta-data android:name="ymp_gcm_sender_id" android:value="number:SENDER_ID"/>
    
    <!-- If you have a dependency on com.google.firebase:firebase-auth -->
    <meta-data android:name="ymp_firebase_api_key" android:value="API_KEY"/>
    Copied to clipboard

    APP_ID — ID of the app in Firebase. You can find it in the Firebase console: go to the Project settings. In the Your application section copy the value of the application ID field.

    SENDER_ID — The unique ID of the sender in Firebase. You can find it in the Firebase console: go to Project settings → Cloud Messaging and copy the value of the Sender ID field.

    API_KEY — App key in Firebase. You can find it in the current_key field of the google-services.json file. You can download the file in the Firebase console.

    Attention. You should initialize default Firebase project.

Step 3. Initialize the library

Initialize the library in the app — extend the Application class and override the onCreate() method as follows:

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        YandexMetricaPush.init(getApplicationContext());
    }
}
Copied to clipboard
Attention. The AppMetrica Push SDK library must be initialized in the main process.

Step 4. Configuring Silent Push Notifications

Configure processing silent push notifications.

  1. Create a special BroadcastReceiver:

    import com.yandex.metrica.push.YandexMetricaPush;
    public class SilentPushReceiver extends BroadcastReceiver {
        @Override
        public void onReceive(Context context, Intent intent) {
            // Extract push message payload from your push message.
            String payload = intent.getStringExtra(YandexMetricaPush.EXTRA_PAYLOAD);
            ...
        }
    }
    Copied to clipboard
  2. Make changes in the application element in the AndroidManifest.xml file:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android">
      <application>
      ...
        <receiver android:name=".SilentPushReceiver">
          <intent-filter>
            <!-- Receive silent push notifications. -->
            <action android:name="${applicationId}.action.ymp.SILENT_PUSH_RECEIVE"/>
          </intent-filter>
        </receiver>
      ...
      </application>
    </manifest>
    Copied to clipboard

    applicationId — Unique app ID in Gradle (package name). For example, com.example.name.

Step 5. (Optional) Enable push tokens update

The FCM service can withdraw the push token of the device, for example, if the user did not launch the application for a long time. AppMetrica stores push tokens on the server and can not send a push notification to a device with an obsolete token.

To automatically collect current push token go to the application settings in the AppMetrica interface and enable the Update tokens with a Silent Push notification option in the Push Notifications tab.

Attention. Ensure that the application is configured to handle silent push notifications. If the configuration is incorrect, users will see blank notifications when updating the push token.

Sending additional information

You can send additional information with the push notification if necessary. This data is specified in the AppMetrica web interface when configuring the push campaign.

public class TargetActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(saveInstanceState);
        handlePayload(getIntent());
    }

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        handlePayload(intent);
    }

    private void handlePayload(Intent intent) {
        // Handle your payload.
        String payload = intent.getStringExtra(YandexMetricaPush.EXTRA_PAYLOAD);
        ...
    }
}
Copied to clipboard

Detecting the application launch via push notification

To distinguish app launches initiated by opening an AppMetrica push notification from the total number of app starts, you should check the Intent action of the app. If you specified a deeplink as the action, this will be the Intent action. If the action is set as opening the app, the Intent action passes the value YandexMetricaPush#OPEN_DEFAULT_ACTIVITY_ACTION.