SDK push-уведомлений для Defold (версия 2.3.0)

Условия корректной работы SDK

Ниже перечислены условия работы push-уведомлений.

Важно

• Подпись тестируемой сборки (например, debug) приложения должна совпадать с подписью сборки приложения, которая была загружена в консоль и прошла модерацию ранее (например, release).

• Используется актуальная версия SDK.
• Приложение загружено в Консоль RuStore.
• Приложение прошло модерацию (публиковать приложение необязательно).
• На устройстве пользователя установлена актуальная версия RuStore.
• Приложение RuStore поддерживает функциональность push-уведомлений.
• Приложению RuStore разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
• Отпечаток подписи приложения должен совпадать с отпечатком, добавленным в Консоль RuStore.

Пример реализации

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

Подключение в проект

Установка пакета

Расширение extension-rustore-push может быть установлено через подключение зависимости и локально. Локальная установка позволяет вносить изменения в исходный код проекта и редактировать манифест приложения для тонкой настройки SDK.

Установка через зависимости

Правила подключения внешних зависимостей описаны в руководстве пользователя Defold на странице Library.

1. Откройте настройки вашего проекта на вкладке Project (game.project > Project);
2. Добавьте в поле Dependencies ссылку на пакет с расширением https://gitflic.ru/project/rustore/defold-extension-rustore-push/file/downloadAll?branch=master.

подсказка

Рекомендуется использовать ссылку на определённый релиз расширения.

Локальная установка (с возможностью изменения кода)

1. Скопируйте проект плагина и приложения-примера из официального репозитория RuStore на GitFlic;
2. Скопируйте папку extension-rustore-push в корень вашего проекта;
3. Откройте настройки вашего проекта на вкладке Library (game.project > Library);
4. В поле Include Dirs укажите имя папки пакета extension-rustore-push, несколько имен разделяются пробелами.

Редактирование манифеста приложения

Плагин extension-rustore-push внесет изменения в манифест вашего приложения.

подсказка

Изменить это поведение можно в локальной копии extension-rustore-push в файле манифеста extension-rustore-push/manifests/android/AndroidManifest.xml.

Плагин добавит к манифесту вашего приложения службу RustoreMessagingService.

AndroidManifest.xml

<service
    android:name="ru.rustore.defoldpush.RustoreMessagingService"
    android:exported="true"
    tools:ignore="ExportedService">
    <intent-filter>
        <action android:name="ru.rustore.sdk.pushclient.MESSAGING_EVENT" />
    </intent-filter>
</service>

Для задания параметров инициализации push-клиента плагин добавит к манифесту вашего приложения параметры project_id и params_class через тэг meta-data. Дополнительная информация о project_id и params_class находится в разделе Инициализация.

AndroidManifest.xml

<meta-data
    android:name="ru.rustore.sdk.pushclient.project_id"
    android:value="{{android.rustore_project_id}}" />
<meta-data
    android:name="ru.rustore.sdk.pushclient.params_class"
    android:value="ru.rustore.defoldpush.RuStorePushClientParams" />

Если нужно изменить иконку или цвет стандартной нотификации, добавьте следующий код.

AndroidManifest.xml

<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_icon"
    android:resource="@drawable/ic_baseline_android_24" />
<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_color"
    android:resource="@color/your_favorite_color" />

Если нужно переопределить канал уведомлений, добавьте следующий код.

AndroidManifest.xml

<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_channel_id"
    android:value="@string/pushes_notification_channel_id" />

При добавлении канала push-уведомлений вы должны создать канал самостоятельно.

Прием пушей из консоли RuStore

Чтобы иметь возможность получать push-сообщения с объектом notification, вы должны сделать PushDispatchActivity основным активити. Для этого добавьте следующую запись в манифест вашего проекта.

AndroidManifest.xml

<activity android:name="ru.rustore.defoldpush.PushDispatchActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Одновременно, вы должны удалить следующий <intent-filter> из активити com.dynamo.android.DefoldActivity.

AndroidManifest.xml

<intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
</intent-filter>

Для выполнения этих действий вы можете воспользоваться примером ExtendedAndroidManifest.xml из папки /extension-rustore-push/manifests/android/. Откройте game.project вашего проекта и укажите путь до измененного файла манифеста в поле Manifest раздела Android.

Путь к файлу ExtendedAndroidManifest.xml

/extension-rustore-push/manifests/android/ExtendedAndroidManifest.xml

Запрос разрешения на показ уведомлений в Android 13+

В версии Android 13 появилось новое разрешение для отображения push-уведомлений. Это затронет все приложения, которые работают на Android 13 или выше и используют RuStore Push SDK.

По умолчанию RuStore Push SDK версии 1.4.0 и выше включает разрешение POST_NOTIFICATIONS, определённое в манифесте. Однако приложению также нужно запросить это разрешение во время выполнения через константу android.permission.POST_NOTIFICATIONS. Приложение сможет показывать push-уведомления, только когда пользователь предоставит на это разрешение.

Запрос разрешения на показ push-уведомлений.

Activity/Fragment

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
    registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
        if (isGranted) {
            // RuStore Push SDK (and your app) can post notifications.
        } else {
            // TODO: Inform user that your app will not show notifications.
        }
    });

private void askNotificationPermission() {
    // This is only necessary for API level>= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT>= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // RuStore Push SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}

Инициализация

Для инициализации понадобится идентификатор проекта из RuStore Консоль. Чтобы получить его, на странице приложения перейдите в раздел Push-уведомления > Проекты и скопируйте значение в поле ID проекта.

Инициализация плагина

Плагин добавит в манифест вашего приложения следующий код.

подсказка

Изменить это поведение можно в локальной копии extension-rustore-push в файле манифеста extension-rustore-push/manifests/android/AndroidManifest.xml.

AndroidManifest.xml

<meta-data
    android:name="ru.rustore.sdk.pushclient.project_id"
    android:value="{{android.rustore_project_id}}" />
<meta-data
    android:name="ru.rustore.sdk.pushclient.params_class"
    android:value="ru.rustore.defoldpush.RuStorePushClientParams" />

• projectId — идентификатор проекта из RuStore Консоль. Чтобы получить его, на странице приложения перейдите в раздел Push-уведомления > Проекты и скопируйте значение в поле ID проекта.
• params_class (опционально) — полное имя класса своей реализации AbstractRuStorePushClientParams. Параметр нужен для указания дополнительных параметров инициализации push-клиента.

Пример реализации наследника AbstractRuStorePushClientParams находится в файле extension-rustore-push/src/java/ru/rustore/defoldpush/RuStorePushClientParams.java.

Пример RuStorePushClientParams.java

package ru.rustore.defoldpush;

import java.util.HashMap;
import java.util.Map;

import android.content.Context;

import com.vk.push.common.clientid.ClientIdCallback;

import ru.rustore.sdk.pushclient.common.logger.DefaultLogger;
import ru.rustore.sdk.pushclient.common.logger.Logger;
import ru.rustore.sdk.pushclient.provider.AbstractRuStorePushClientParams;

public class RuStorePushClientParams extends AbstractRuStorePushClientParams {
    RuStorePushClientParams(Context context) {
        super(context);
    }

    @Override
    public Logger getLogger() {
        return new DefaultLogger(Push.TAG);
    }

    @Override
    public boolean getTestModeEnabled() {
        return false;
    }

    @Override
    public Map<String, Object> getInternalConfig() {
       HashMap<String, Object> map = new HashMap<>(1);
       map.put("type", "defold");
       return map;
    }

    @Override
    public ClientIdCallback getClientIdCallback() {
        return Push.getInstance();
    }
}

предупреждение

В реализации класса AbstractRuStorePushClientParams должен быть только один конструктор с одним аргументом Context.

Для инициализации сервиса push-уведомлений добавьте значение в game_project вашего проекта. Откройте его любым удобным текстовым редактором и в секции [android] добавьте следующий код.

[android]
rustore_project_id = %your project id%
package = %your package%

• your project id — идентификатор проекта из RuStore Консоль. Чтобы получить его, на странице приложения перейдите в раздел Push-уведомления > Проекты и скопируйте значение в поле ID проекта.
• your package — имя пакета Android из RuStore Консоль. Чтобы получить его, на странице приложения перейдите в раздел Push-уведомления > Проекты и скопируйте значение в поле Android Package Name.

Настройки по умолчанию для заголовка и тела push-уведомления

Вы можете установить значения по умолчанию для заголовка и тела, если они не указаны в поле data push-уведомления.

[android]
push_field_title = default push title
push_field_text = default push body

Сервис push-уведомлений запускается автоматически на устройствах Android при вызове метода set_on_token.

Вызов метода set_on_token

ruStorePush.set_on_token()

Логирование событий

События sdk push-уведомлений по умолчанию логируются. Объект реализующий интерфейс Logger возвращается в методе getLogger класса RuStorePushClientParams — реализации абстрактного класса AbstractRuStorePushClientParams. Если не передать Logger, SDK использует реализацию по умолчанию с AndroidLog.

Интерфейс Logger

public interface Logger {
    void verbose(String message, Throwable throwable);
    void debug(String message, Throwable throwable);
    void info(String message, Throwable throwable);
    void warn(String message, Throwable throwable);
    void error(String message, Throwable throwable);

    Logger createLogger(String tag);
}

Пример реализации логгера

public class DefaultLogger implements Logger {
    private final String tag;
    public DefaultLogger(String tag) {
        this.tag = tag;
    }
    @Override
    public void debug( @NonNull String message, Throwable throwable) {
        Log.d(tag, message, throwable);
    }
    @Override
    public void error( @NonNull String message, Throwable throwable) {
        Log.e(tag, message, throwable);
    }
    @Override
    public void info( @NonNull String message, @Nullable Throwable throwable) {
        Log.i(tag, message, throwable);
    }
    @Override
    public void verbose( @NonNull String message, @Nullable Throwable throwable) {
        Log.v(tag, message, throwable);
    }
    @Override
    public void warn( @NonNull String message, @Nullable Throwable throwable) {
        Log.w(tag, message, throwable);
    }
    @NonNull
    @Override
    public Logger createLogger(@NonNull String newTag) {
        String combinedTag = (tag != null ) ? tag +  ":" + newTag : newTag;
        return new DefaultLogger(combinedTag);
    }
}

Метод getLogger

package ru.rustore.defoldpush;

import android.content.Context;

import ru.rustore.sdk.pushclient.common.logger.DefaultLogger;
import ru.rustore.sdk.pushclient.common.logger.Logger;
import ru.rustore.sdk.pushclient.provider.AbstractRuStorePushClientParams;

public class RuStorePushClientParams extends AbstractRuStorePushClientParams {
    RuStorePushClientParams(Context context) {
        super(context);
    }

    @Override
    public Logger getLogger() {
        return new DefaultLogger(Push.TAG);
    }
}

Работа с сегментами пользователей

Сегмент — это группа пользователей, которых вы выбираете по определенным параметрам. Например, пользователи, которые приносят наибольший доход, или пользователи со старой версией Android. Подробности о сегментах — в документации MyTracker.

Чтобы начать работу с сегментами, используйте метод set_client_id_callback с параметрами CLIENT_ID_VALUE и CLIENT_ID_TYPE.

Вызов метода set_client_id_callback

local CLIENT_ID_TYPE = ruStorePush.CLIENT_AID_NOT_AVAILABLE
local CLIENT_ID_VALUE = ""

ruStorePush.set_client_id_callback(function(self)
    return CLIENT_ID_VALUE, CLIENT_ID_TYPE
end)

• CLIENT_ID_TYPE — тип идентификатора:
  • CLIENT_AID_NOT_AVAILABLE — рекламный идентификатор не используется;
  • CLIENT_GAID — рекламный идентификатор Google;
  • CLIENT_OAID — рекламный идентификатор Huawei.
• CLIENT_ID_VALUE — значение идентификатора.

Методы для работы с push-токеном

Получение push-токена пользователя

Для получения push-токенов выполните подписку на событие new_token с помощью метода set_on_token.

local function new_token(self, token, error)
    if token then
       print(token)
    else
       print(error.error)
    end
end

local function push_android()
    ruStorePush.set_on_token(new_token)
end

предупреждение

Если у пользователя нет push-токена, метод создаст и вернёт новый push-токен.

Удаление push-токена пользователя

Для удаления push-токенов используйте метод delete_token.

Вызов метода delete_token

ruStorePush.delete_token(function (self, error)
    if error then
        print("Error deleting token: %s", error.error)
    else
        print("push token deleted")
    end
end)

Методы для работы с push-топиком

Подписка на push-уведомления по топику

Для подписки на топик используйте метод topic_subscribe.

Вызов метода topic_subscribe

local TOPIC_NAME = "defold"

ruStorePush.topic_subscribe("defold", function (self, error)
    if error then
        print("Error to subscribe: %s", error.error)
    else
        print("subscribe to: defold")
    end
end)

TOPIC_NAME — имя топика.

Отписка от push-уведомлений по топику

Для отписки от сообщений топика используйте метод topic_unsubscribe.

Вызов метода topic_subscribe

local TOPIC_NAME = "defold"

ruStorePush.topic_unsubscribe(TOPIC_NAME, function (self, error)
    if error then
        print("Error to unsubscribe: %s", error.error)
    else
        print("unsubscribe from: defold")
    end
end)

TOPIC_NAME — имя топика.

Получение информации из push-уведомления

Чтобы получить информацию о push-уведомлениях, добавьте callback ruStorePush.set_on_message().

Для получения информации о push-уведомлениях выполните подписку на событие on_message с помощью метода set_on_message.

Подписка на событие

local function listener(self, payload, activated)
    -- The payload arrives here.
    pprint(payload)
end
 
local function push_android()
    ruStorePush.set_on_message(listener)
end

• payload (lua table) — поле data push-уведомления;
• activated (bool) — информация о переходе пользователя в приложение по нажатию на push-уведомление.

предупреждение

Не отправляйте push-уведомления с параметрами notification и android.notification.title: по таким уведомлениям невозможно будет перейти в приложение.

Указывайте следующие параметры в поле data:

• title — заголовок push-уведомления.
• message — тело push-уведомления.

См. также

• Отправка push-уведомлений (API)
• Отправка push-уведомлений по топикам (API)
• Работа с сегментами пользователей (API)