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

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

Условия работы push-уведомлений:

• На устройстве пользователя установлена актуальная версия RuStore.
• Приложение RuStore должно поддерживать функциональность push-уведомлений.
• Приложению RuStore разрешен доступ к работе в фоновом режиме.
• Пользователь авторизован в RuStore.
• Отпечаток подписи приложения должен совпадать с отпечатком, добавленным в Консоль 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)