SDK push-уведомлений для Defold (версия 2.1.1)
Условия корректной работы SDK
Условия работы push-уведомлений:
- Используется актуальная версия SDK.
- Приложение загружено в Консоль RuStore.
- Приложение прошло модерацию (публиковать приложение необязательно).
- На устройстве пользователя установлена актуальная версия RuStore.
- Приложение RuStore поддерживает функциональность push-уведомлений.
- Приложению RuStore разрешен доступ к работе в фоновом режиме.
- Пользователь авторизован в RuStore.
- Отпечаток подписи приложения должен совпадать с отпечатком, добавленным в Консоль RuStore.
Пример реализации
Ознакомьтесь с приложением-примером, чтобы узнать, как правильно интегрировать SDK push-уведомлений.
Подключение в проект
Установка пакета
Расширение extension-rustore-push
может быть установлено через подключение зависимости и локально. Локальная установка позволяет вносить изменения в исходный код проекта и редактировать манифест приложения для тонкой настройки SDK.
** Установка через зависимости **
Правила подключения внешних зависимостей описаны в руководстве пользователя Defold на странице Library.
-
Откройте настройки вашего проекта на вкладке
Project
(game.project → Project); -
Добавьте в поле
Dependencies
ссылку на пакет с расширением https://gitflic.ru/project/rustore/defold-extension-rustore-push/file/downloadAll?branch=master.
Рекомендуется использовать ссылку на определённый релиз расширения.
** Локальная установка (с возможностью изменения кода) **
-
Скопируйте проект плагина и приложения-примера из официального репозитория RuStore на GitFlic;
-
Скопируйте папку
extension-rustore-push
в корень вашего проекта; -
Откройте настройки вашего проекта на вкладке
Library
(game.project → Library); -
В поле
Include Dirs
укажите имя папки пакетаextension-rustore-push
, несколько имен разделяются пробелами.
Редактирование манифеста приложения
Плагин extension-rustore-push
внесет изменения в манифест вашего приложения.
Изменить это поведение можно в локальной копии extension-rustore-push
в файле манифеста extension-rustore-push / manifests / android / AndroidManifest.xml
.
Плагин добавит к манифесту вашего приложения службу RustoreMessagingService
.
<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
находится в разделе Инициализация.
<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" />
Если нужно изменить иконку или цвет стандартной нотификации, добавьте:
<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" />
Если нужно переопределить канал уведомлений, добавьте:
<meta-data
android:name="ru.rustore.sdk.pushclient.default_notification_channel_id"
android:value="@string/pushes_notification_channel_id" />
При добавлении канала push-уведомлений вы должны создать канал самостоятельно.
Прием пушей из консоли RuStore
Чтобы иметь возможность получать push-сообщения с объектом notification
, вы должны сделать PushDispatchActivity
основным активити. Для этого добавьте следующую запись в манифест вашего проекта:
<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
:
<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
.
/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-уведомлений:
// 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 проекта».
![img](/help/zh/assets/images/project-id-c3f7d16c6ea4bb0472a203c945461513.webp)
Инициализация плагина
Плагин добавит в манифест вашего приложения следующий код:
Изменить это поведение можно в локальной копии extension-rustore-push
в файле манифеста extension-rustore-push / manifests / android / 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
:
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
:
ruStorePush.set_on_token()
Логирование событий
События sdk push-уведомлений по умолчанию логируются. Объект реализующий интерфейс Logger
возвращается в методе getLogger
класса RuStorePushClientParams
— реализации абстрактного класса AbstractRuStorePushClientParams
. Если не передать Logger
, SDK использует реализацию по умолчанию с AndroidLog
.
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);
}
}
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
:
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
:
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
:
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
:
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-уведомления.