Подключение и инициализация

Push SDK под Android предоставляется в виде библиотеки в формате AAR.
Библиотека доступна в Maven-репозитории.

Ниже описаны этапы подключения и инициализации AppMetrica Push SDK:

Шаг 1. Подготовьте приложение

Перед подключением библиотеки AppMetrica Push SDK, подготовьте ваше приложение:

  1. Подключите основную библиотеку AppMetrica SDK не ниже версии 6.0.0.
  2. Настройте приложение для отправки push-уведомлений.

Шаг 2. Подключите библиотеку

Push SDK использует библиотеку OKHttp для кэширования изображений, которые показываются в push-уведомлениях.
Правила кэширования берутся из HTTP-заголовка cache-control.
Если вы не хотите, чтобы изображения кэшировались, подключите библиотеку без кэширования.

  1. Если вы используете Gradle для сборки приложения, добавьте следующую зависимость в Gradle файл приложения:

    С кэшированием
    dependencies {
    // AppMetrica Push SDK.
    implementation("io.appmetrica.analytics:push:4.2.1")
    implementation("androidx.legacy:legacy-support-v4:1.0.0")
}

    dependencies {
    // AppMetrica Push SDK.
    implementation "io.appmetrica.analytics:push:4.2.1"
    implementation "androidx.legacy:legacy-support-v4:1.0.0"
}
    Без кэширования
    dependencies {
    // AppMetrica Push SDK.
    implementation("io.appmetrica.analytics:push:4.2.1") {
      exclude(group = "com.squareup.okhttp3", module = "okhttp")
    }
    implementation("androidx.legacy:legacy-support-v4:1.0.0")
}

    dependencies {
    // AppMetrica Push SDK.
    implementation "io.appmetrica.analytics:push:4.2.1" {
     exclude group: "com.squareup.okhttp3", module: "okhttp"
    }
    implementation "androidx.legacy:legacy-support-v4:1.0.0"
}

  2. Подключите транспорт.

    1. Если вы используете Gradle для сборки приложения, добавьте следующую зависимость в Gradle файл приложения:

      • app/build.gradle.kts

        dependencies {
        // minimum support version 20.3.0
        implementation("com.google.firebase:firebase-messaging:22.0.0")
        implementation("com.google.android.gms:play-services-base:17.5.0")
    }

      • app/build.gradle

        dependencies {
        // minimum support version 20.3.0
        implementation "com.google.firebase:firebase-messaging:22.0.0"
        implementation "com.google.android.gms:play-services-base:17.5.0"
    }

      Используемая при разработке версия указана в репозитории.

    2. Инициализируйте Firebase, используя один из способов:

      Использование Google Services Plugin

      1. Загрузите конфигурационный файл google-services.json и разместите его в каталоге модуля проекта (например, app).

      2. Для корректной работы с файлом подключите плагин Google Services в проект, добавив следующие строки в Gradle файл:

        проекта

        • build.gradle.kts

          buildscript {
    dependencies {
        classpath("com.google.gms:google-services:4.4.0")
    }
}

        • build.gradle

          buildscript {
    dependencies {
        classpath "com.google.gms:google-services:4.4.0"
    }
}

        приложения (модуля)

        • app/build.gradle.kts

          apply(plugin = "com.google.gms.google-services")

        • app/build.gradle

          apply plugin: "com.google.gms.google-services"
      Без использования плагина

      Внесите изменения в элемент application файла AndroidManifest.xml:

      <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"/>
<meta-data android:name="ymp_firebase_default_api_key" android:value="API_KEY"/>
<meta-data android:name="ymp_firebase_default_project_id" android:value="PROJECT_ID"/>

      APP_ID — идентификатор приложения в Firebase. Его можно узнать в консоли Firebase: перейдите в Настройки проекта. В разделе Ваши приложения скопируйте значение поля Идентификатор приложения.

      SENDER_ID— уникальный идентификатор отправителя в Firebase. Его можно узнать в консоли Firebase: перейдите во вкладку Настройки проекта → Cloud Messaging и скопируйте значение поля Идентификатор отправителя.

      API_KEY — ключ приложения в Firebase. Его можно найти в поле current_key файла google-services.json. Файл можно скачать из консоли Firebase.

      PROJECT_ID — id приложения в Firebase. Его можно найти в поле project_id файла google-services.json. Файл можно скачать из консоли Firebase.

      Использование с другими Firebase-проектами

      Внесите изменения в элемент application файла AndroidManifest.xml:

      <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"/>
<meta-data android:name="ymp_firebase_api_key" android:value="API_KEY"/>
<meta-data android:name="ymp_firebase_project_id" android:value="PROJECT_ID"/>

      APP_ID — идентификатор приложения в Firebase. Его можно узнать в консоли Firebase: перейдите в Настройки проекта. В разделе Ваши приложения скопируйте значение поля Идентификатор приложения.

      SENDER_ID— уникальный идентификатор отправителя в Firebase. Его можно узнать в консоли Firebase: перейдите во вкладку Настройки проекта → Cloud Messaging и скопируйте значение поля Идентификатор отправителя.

      API_KEY — ключ приложения в Firebase. Его можно найти в поле current_key файла google-services.json. Файл можно скачать из консоли Firebase.

      PROJECT_ID — id приложения в Firebase. Его можно найти в поле project_id файла google-services.json. Файл можно скачать из консоли Firebase.

      Внимание

      Вам необходимо самостоятельно инициализировать Firebase-проект по умолчанию.

    1. Добавьте HMS Push Kit в проект. Используемая при разработке версия указана в репозитории.

    2. Если вы используете Gradle для сборки приложения, добавьте следующую зависимость в Gradle файл приложения:

      • app/build.gradle.kts

        dependencies {
    implementation("io.appmetrica.analytics:push-provider-hms:4.2.1")
}

      • app/build.gradle

        dependencies {
    implementation "io.appmetrica.analytics:push-provider-hms:4.2.1"
}

      Внимание

      Если вы собираетесь использовать только HMS, исключите Firebase зависимость из основной библиотеки:

      • app/build.gradle.kts

        dependencies {
    implementation("io.appmetrica.analytics:push:4.2.1") {
        exclude(group =  "io.appmetrica.analytics", module = "push-provider-firebase")
    }
}

      • app/build.gradle

        dependencies {
    implementation("io.appmetrica.analytics:push:4.2.1") {
        exclude group: "io.appmetrica.analytics", module: "push-provider-firebase"
    }
}

    3. Внесите изменения в элемент application файла AndroidManifest.xml:

      <meta-data android:name="ymp_hms_default_app_id" android:value="number:APP_ID"/>

      APP_ID — идентификатор приложения в HMS. Его можно найти в поле app_id файла agconnect-services.json. Файл можно скачать из консоли Huawei.

AppMetrica Push SDK умеет работать одновременно с Firebase и с HMS.

Шаг 3. Инициализируйте библиотеку

Инициализируйте библиотеку в приложении — объявите производный класс от базового класса Application и переопределите метод onCreate() следующим образом:

Только Firebase
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AppMetricaPush.activate(applicationContext)
    }
}

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        AppMetricaPush.activate(getApplicationContext());
    }
}
Только HMS
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AppMetricaPush.activate(applicationContext, HmsPushServiceControllerProvider(this))
    }
}

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        AppMetricaPush.activate(getApplicationContext(), new HmsPushServiceControllerProvider(this));
    }
}
Firebase и HMS

Добавьте зависимость, чтобы иметь возможность вызвать FirebasePushServiceControllerProvider(this):

dependencies {
    implementation("io.appmetrica.analytics:push-provider-firebase:$appmetrica_push_version")
}

Переопределите класс:

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AppMetricaPush.activate(
            applicationContext,
            FirebasePushServiceControllerProvider(this),
            HmsPushServiceControllerProvider(this)
        )
    }
}

Добавьте зависимость, чтобы иметь возможность вызвать FirebasePushServiceControllerProvider(this):

dependencies {
    implementation "io.appmetrica.analytics:push-provider-firebase:$appmetrica_push_version"
}

Переопределите класс:

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        AppMetricaPush.activate(
            getApplicationContext(),
            new FirebasePushServiceControllerProvider(this),
            new HmsPushServiceControllerProvider(this)
        );
    }
}

Внимание

Библиотеку AppMetrica Push SDK необходимо инициализировать в главном процессе.

Шаг 4. (Опционально) Настройте Silent Push Notifications

Настройте обработку push-уведомлений, которые не предполагают вывод сообщений (Silent Push Notifications).

  1. Создайте специальный BroadcastReceiver:

    class SilentPushReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        // Extract push message payload from your push message.
        val payload = intent.getStringExtra(AppMetricaPush.EXTRA_PAYLOAD)
    }
}

    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(AppMetricaPush.EXTRA_PAYLOAD);
    }
}

  2. Внесите изменения в элемент application файла AndroidManifest.xml:

    <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>

    applicationId — уникальный идентификатор приложения в Gradle (имя пакета).
    Например, com.example.name.

Шаг 5. (Опционально) Включите актуализацию push‑токенов

Если у вас есть свой сервис для обработки пушей (класс, унаследованный от FirebaseMessagingService или HmsMessageService), проверьте, что не обрабатываете пуши от AppMetrica.

Чтобы проверить, что пуш не от AppMetrica, воспользуйтесь методом AppMetricaMessagingService.isNotificationRelatedToSDK или AppMetricaHmsMessagingService.isNotificationRelatedToSDK.

Сервис FCM может отозвать push-токен устройства, например, если пользователь долго не запускал приложение. AppMetrica хранит push-токены на сервере и не может отправить push-уведомление на устройство с устаревшим токеном.

Чтобы автоматически собирать актуальные push-токены, перейдите в настройки приложения в веб-интерфейсе AppMetrica и выберите опцию Актуализировать токены с помощью Silent Push-уведомлений во вкладке Push-уведомления.

Шаг 6. (Опционально) Настройте использование с другими push SDK

Если в приложение интегрировано несколько SDK для обработки push-уведомлений, выполните инструкцию Использование с другими push-сервисами.

Необходимо выполнить дополнительные настройки, иначе возможны проблемы с обработкой push-уведомлений.

Отправка дополнительной информации

При необходимости вы можете передавать вместе с push-уведомлением дополнительную информацию. Эти данные указываются в веб-интерфейсе AppMetrica при настройке push-кампании.

class TargetActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        handlePayload(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handlePayload(intent)
    }

    private fun handlePayload(intent: Intent) {
        // Handle your payload.
        val payload = intent.getStringExtra(AppMetricaPush.EXTRA_PAYLOAD)
    }
}

public class TargetActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        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(AppMetricaPush.EXTRA_PAYLOAD);
    }
}

Отслеживание запуска приложения через push-уведомление

Чтобы отличить запуски приложения по открытию push-уведомления AppMetrica Push SDK от общего числа запусков, необходимо проверить Intent action приложения:

  • Если в качестве действия вы указали deeplink, он будет являться Intent action.

  • Если в качестве действия выбрано открытие приложения, Intent action будет передавать значение AppMetricaPush#OPEN_DEFAULT_ACTIVITY_ACTION.

Настройка иконки по умолчанию

Чтобы указать иконку push-уведомления по умолчанию, внесите изменения в элемент application файла AndroidManifest.xml:

<meta-data android:name="io.appmetrica.analytics.push.default_notification_icon"
           android:resource="ICON_RESOURCE"/>

ICON_RESOURCE — ресурс иконки.
Например, @drawable/large_icon.

Изменение настроек канала уведомлений

Вы можете изменить настройки канала уведомлений, используемого по умолчанию. Например, добавить в него описание или изменить важность.

Изменить настройки канала можно только до его создания, то есть до отправки первого пуша через AppMetrica.

Для получения дефолтного канала вызовите метод getDefaultNotificationChannel():

AppMetricaPush.getDefaultNotificationChannel()?.apply {
    description = "Push from AppMetrica"
    importance = NotificationManager.IMPORTANCE_HIGH
    // Modify NotificationChannel properties
}

NotificationChannel channel = AppMetricaPush.getDefaultNotificationChannel();
if (channel != null) {
    channel.setDescription("Push from AppMetrica");
    channel.setImportance(NotificationManager.IMPORTANCE_HIGH);
    // Modify NotificationChannel
}

Узнать больше

Если вы не нашли ответ на свой вопрос, то вы можете задать его через форму обратной связи. Пожалуйста, опишите возникшую проблему как можно подробнее. Если возможно, приложите скриншот.

Написать в службу поддержки
Предыдущая
Справочник SDK
Следующая
Настройка приложения