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

Как push-sdk получает уведомления

На мобильном устройстве пользователя должно быть установлено приложение, которое отвечает за доставку push-уведомлений от нашего SDK. Такое приложение называется «дистрибьютором». Оно периодически обращается к серверу, проверяет наличие новых уведомлений для конкретного приложения, где включён наш SDK, и при их появлении отправляет push-уведомления в конечное приложение.

Основным дистрибьютором служит RuStore, однако если у пользователя нет RuStore, роль резервного дистрибьютора может взять на себя одно из других приложений VK. Выбор делается удалённо на сервере, поэтому мы не раскрываем полный список возможных резервных вариантов. Состав приложений-дистрибьюторов может динамически меняться, поэтому на устройстве конкретного пользователя в любой момент может оказаться другое приложение в этой роли.

Для проверки того, что приложение-дистрибьютор установлено на устройстве пользователя, используйте метод RuStorePushClient.checkPushAvailability.

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

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

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

Важно

• Подпись и package name различных типов сборок вашего приложения (debug, release и т.д.) могут отличаться друг от друга. В таком случае вы должны создать в разделе Push-уведомления > Проекты из RuStore Консоль проект под каждый тип сборки..

• Используется актуальная версия SDK.
• Загружены данные о приложении в разделе Push-уведомления > Проекты из RuStore Консоль.

• На устройстве пользователя установлено приложение-дистрибьютор (RuStore и т.д.)

  Для проверки того, что приложение-дистрибьютор установлено на устройстве пользователя, используйте метод RuStorePushClient.checkPushAvailability..
• Если установлено приложение RuStore, то ему разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
• Отпечаток подписи приложения, установленного на девайсе, совпадает с отпечатком подписи приложения, которое добавлено в разделе 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 проекта.

Обратите внимание

Обратите внимание, что Push SDK не поддерживает работу в нескольких процессах одновременно.
Если ваше приложение использует несколько процессов, необходимо инициализировать SDK только в главном процессе.

Если инициализация происходит в дополнительном процессе, это может привести к некорректной работе push-уведомлений.

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

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

подсказка

Изменить это поведение можно в локальной копии 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)