Функционал SDK
Предварительно вам необходимо настроить SDK для работы с вашим приложением. Подробная инструкция находится здесь.
Работа со статусами подписки
Изменение статуса подписки
AltcraftSDK (React Native)
└─ pushSubscriptionFunctions
// Подписка (статус = SUBSCRIBED)
├─ function pushSubscribe(
│ sync: boolean | null = true,
│ profileFields: Record<string, unknown> | null = null,
│ customFields: Record<string, unknown> | null = null,
│ cats: CategoryData[] | null = null,
│ replace: boolean | null = null,
│ skipTriggers: boolean | null = null
│ ): void
// Приостановка (статус = SUSPENDED)
├─ function pushSuspend(
│ sync: boolean | null = true,
│ profileFields: Record<string, unknown> | null = null,
│ customFields: Record<string, unknown> | null = null,
│ cats: CategoryData[] | null = null,
│ replace: boolean | null = null,
│ skipTriggers: boolean | null = null
│ ): void
// Отписка (статус = UNSUBSCRIBED)
└─ function pushUnSubscribe(
sync: boolean | null = true,
profileFields: Record<string, unknown> | null = null,
customFields: Record<string, unknown> | null = null,
cats: CategoryData[] | null = null,
replace: boolean | null = null,
skipTriggers: boolean | null = null
): void
function pushSubscribe()— выполняет подписку на push-уведомления;function pushUnSubscribe()— отменяет подписку на push-уведомления;function pushSuspend()— приостанавливает подписку на push-уведомления (уведомления не приходят, но при этом не создается событие отписки в профиле пользователя);function unSuspendPushSubscription()— используется для созданияLogIn-,LogOut-переходов.
Функции этой группы имеют одинаковую сигнатуру, содержащую следующие параметры:
sync: Boolean
По умолчанию: true
Обязательный: Нет
Описание: Флаг, устанавливающий синхронность выполнения запроса.
Успешное выполнение запроса:
В случае успешного выполнения запроса данной группы функций будет создано событие с кодом 230, 231 или 232, содержащее значение event.value, определяемое в зависимости от флага синхронизации:
Если sync == true
ResponseWithHttpCode
├─ httpCode: 200
└─ response
├─ error: 0
├─ errorText: ""
└─ profile
├─ id: "your id"
├─ status: "subscribed"
├─ isTest: false
└─ subscription
├─ subscriptionId: "your subscriptionId"
├─ hashId: "7f31a9c4"
├─ provider: "android-firebase"
├─ status: "subscribed"
├─ fields
│ ├─ _os_ver: "{\"raw\":\"14\",\"ver\":\"[\\\"14.0\\\", \\\"0.0\\\", \\\"0.0\\\"]\"}"
│ ├─ _device_type: "mob"
│ ├─ _ad_track: "true"
│ ├─ _device_name: "Pixel"
│ ├─ _os_language: "en"
│ ├─ _os_tz: "+0100"
│ ├─ _os: "Android"
│ ├─ _device_model: "Pixel 7"
│ └─ _app_ver: "1.0.0"
└─ cats
└─ [ { name: "developer_news", title: "dev_news", steady: false, active: false } ]
При синхронном запросе в значении события event.value по ключу "response_with_http_code" доступны:
-
httpCode — транспортный код ответа;
-
response — export type, содержащий:
-
error: number | null— внутренний код ошибки сервера (0, если ошибок нет), -
errorText: string | null— текст ошибки (пустая строка, если ошибок нет), -
profile: ProfileData | null— данные профиля, если запрос успешный:- информация о профиле (ProfileData)
- подписка (Subscription)
- если запрос завершился с ошибкой, то вернется только
profile = null
-
export type
export type Response = {
error?: number | null;
errorText?: string | null;
profile?: ProfileData | null;
};
export type ProfileData = {
id?: string | null;
status?: string | null;
isTest?: boolean | null;
subscription?: Subscription | null;
};
export type CategoryData = {
name?: string | null;
title?: string | null;
steady?: boolean | null;
active?: boolean | null;
};
Если sync == false
ResponseWithHttpCode
├─ httpCode: number | null
└─ response: Response | null
├─ error?: number | null
├─ errorText?: string | null
└─ profile?: ProfileData | null // всегда null
При асинхронном запросе в значении события event.value по ключу "response_with_http_code" до ступны:
-
httpCode — транспортный код ответа;
-
response — export type, содержащий:
error: number | null— внутренний код ошибки сервера (0, если ошибок нет),errorText: string | null— текст ошибки (пустая строка, если ошибок нет),profile: ProfileData | null— для асинхронного запроса всегда равенnull.
Выполнение запроса с ошибкой:
Если запрос данной группы функций завершился ошибкой, будет создано событие со следующими кодами:
Операции без автоматического повтора попытки на стороне SDK:
- 430 – подписка на уведомления;
- 431 — приостановка подписки;
- 432 — отписка.
Операции с автоматическим повтором попытки на стороне SDK:
- 530 – подписка на уведомления;
- 531 — приостановка подписки;
- 532 — отписка.
Содержимое события:
- только
httpCode, если сервер Altcraft был недоступен; errorиerrorText, если сервер вернул ошибку.
Получение значений событий
const RESPONSE_CODES = new Set<number>([
230, 231, 232,
430, 431, 432,
531, 532, 533,
]);
subscribeToEvents((event: SdkEvent) => {
if (event.code == null) return;
if (!RESPONSE_CODES.has(event.code)) return;
const raw = event.value?.['response_with_http_code'] as unknown;
const responseWithHttp = raw as ResponseWithHttpCode | null;
if (!responseWithHttp) return;
const httpCode = responseWithHttp.httpCode;
const response = responseWithHttp.response;
const error = response?.error ?? null;
const errorText = response?.errorText ?? null;
const profile = response?.profile ?? null;
const profileId = profile?.id ?? null;
const profileStatus = profile?.status ?? null;
const profileIsTest = profile?.isTest ?? null;
const subscription = profile?.subscription ?? null;
const subscriptionId = subscription?.subscriptionId ?? null;
const hashId = subscription?.hashId ?? null;
const provider = subscription?.provider ?? null;
const subscriptionStatus = subscription?.status ?? null;
const fields = subscription?.fields ?? null;
const cats = subscription?.cats ?? null;
const firstCat = cats?.[0] ?? null;
const catName = firstCat?.name ?? null;
const catTitle = firstCat?.title ?? null;
const catSteady = firstCat?.steady ?? null;
const catActive = firstCat?.active ?? null;
});
profileFields:Record<string, unknown> | null
По умолчанию: null
Обязательный: Нет
Описание: Объект, содержащий поля профиля.
Параметр может принимать как системные поля (например, _fname — имя или _lname — фамилия), так и опциональные (заранее создаются вручную в интерфейсе платформы). Допустимые структуры (JSON-совместимые):
- Скалярные значения:
- String
- Boolean
- Number
null
- Объекты:
Record<string, unknown> - Списки:
unknown[]
Если передано невалидное опциональное поле, запрос завершится с ошибкой:
SDK error: 430
http code: 400
error: 400
errorText: Platform profile processing error: with field "название_поля": Incorrect field
customFields:Record<string, unknown> | null
По умолчанию: null
Обязательный: Нет
Описание: Объект, содержащий поля подписки.
Параметр может принимать как системные поля (например, _device_model — модель устройства или _os — операционная система), так и опциональные (заранее создаются вручную в интерфейсе платформы). Допустимые типы значений (JSON-совместимые, только скаляры):
- String
- Boolean
- Number
null
Если передано невалидное опциональное поле, запрос завершится с ошибкой:
SDK error: 430
http code: 400
error: 400
errorText: Platform profile processing error: field "название_поля" is not valid: failed convert custom field
Большая часть системных полей подписки автоматически собирается SDK и добавляется к push-запросам. К таким системным полям относятся: "_os", "_os_tz", "_os_language", "_device_type", "_device_model", "_device_name", "_os_ver", "_ad_track", "_ad_id".
cats:CategoryData[] | null
По умолчанию: null
Обязательный: Нет
Описание: Категории подписок.
Структура категории:
export type CategoryData = {
name?: string | null;
title?: string | null;
steady?: boolean | null;
active?: boolean | null;
};
При отправке push-запроса с указанием категорий используйте только поля name (название категории) и active (статус активности категории), другие поля не используются в обработке запроса. Поля title и steady заполняются при получении информации о подписке.
Пример запроса:
const cats: CategoryData[] = [
{ name: 'football', active: true },
{ name: 'hockey', active: true },
];
Категории используемые в запросе должны быть предва рительно созданы и добавлены к ресурсу в платформе Altcraft. Если в запросе будет использовано поле, которое не добавлено в ресурс — запрос вернется с ошибкой:
SDK error: 430
http code: 400
error: 400
errorText: Platform profile processing error: field "subscriptions.cats" is not valid: category not found in resource
replace:boolean | null
По умолчанию: null
Обязательный: Нет
Описание: При активации флага все подписки других профилей с тем же push-токеном в текущей базе данных переводятся в статус unsubscribed после успешного запроса.
skipTriggers:boolean | null
По умолчанию: null
Обязательный: Нет
Описание: При активации флага профиль, содержащий данную подписку, будет игнорироваться в триггерах рассылок и сценариев.
Примеры реализации запроса
Пример выполнения запроса подписки на push-уведомления
Минимальная рабочая настройка:
AltcraftSDK.pushSubscribe();
Передача всех доступных параметров:
AltcraftSDK.pushSubscribe(
true,
{ _fname: 'Andrey', _lname: 'Pogodin' },
{ developer: true },
[{ name: 'developer_news', active: true }],
false,
false
);
Для pushSubscribe, pushSuspend, pushUnSubscribe предусмотрен автоматический повтор запроса со стороны SDK если http-код ответа находится в диа пазоне 500..599. Запрос не повторяется, если код ответа в этот диапазон не входит.
Функция unSuspendPushSubscription()
Функция async function unSuspendPushSubscription(): Promise<ResponseWithHttpCode | null> предназначена для создания LogIn-, LogOut-переходов. Она работает следующим образом:
- проводит поиск подписок с тем же push-токеном, что и текущий, не относящихся к профилю, на который указывает текущий JWT-токен;
- меняет статус для найденных подписок с
subscribedнаsuspended; - меняет статус в подписках профиля, на который указывает текущий JWT, с
suspendedнаsubscribed(если профиль, на который указывает JWT, существует и в нем содержатся подписки); - возвращает
ResponseWithHttpCode | null, гдеresponse.profile— текущий профиль, на который указывает JWT (если профиля не существует, то вместоresponse.profileвернетсяnull).
Рекомендуемая реализация LogIn-, LogOut-переходов
LogIn-переход
- Анонимный пользователь входит в приложение. Данному пользователю присвоен
JWT_1, указывающий на базу данных #1Anonymous; - Выполнена подписка на push-уведомления, профиль создан в базе данных #1Anonymous;
- Пользователь регистрируется, ему присваивается
JWT_2, указывающий на базу данных #2Registered; - Вызывается функция
unSuspendPushSubscription()— подписка анонимного пользователя в базе данных #1Anonymous приостанавливается; - Выполняется поиск профиля в базе данных #2Registered для восстановления подписки;
- Так как подписки с таким push-токеном в базе данных #2Registered не существует, функция
unSuspendPushSubscription()вернетnull; - После получения значения
nullможно выполнить запросpushSubscribe(), который создаст новый профиль в базе #2Registered.
LogOut-переход
- Пользователь выполнил выход из профиля на стороне приложения (
LogOut); - Пользователю присваивается
JWT_1, указывающий на базу данных #1Anonymous; - Вызывается функция
unSuspendPushSubscription(), которая приостановит подписку в базе данных #2Registered и сменит статус подписки в базе #1Anonymous наsubscribed; - Запрос вернет профиль #1Anonymous != null — подписка уже существует, новая не требуется.
Пример реализации:
import AltcraftSDK from '@altcraft/react-native-sdk';
import type { ResponseWithHttpCode } from '@altcraft/react-native-sdk';
async function unSuspend(logIn: boolean): Promise<void> {
setAuth(logIn);
const result: ResponseWithHttpCode | null =
await AltcraftSDK.unSuspendPushSubscription();
if (!result) {
AltcraftSDK.pushSubscribe();
return;
}
const httpCode = result.httpCode ?? null;
const subscription = result.response?.profile?.subscription ?? null;
if (httpCode === 200 && subscription == null) {
AltcraftSDK.pushSubscribe();
}
}
export function logIn(): void {
void unSuspend(true);
}
export function logOut(): void {
void unSuspend(false);
}
Запрос статуса подписки
AltcraftSDK
└── function getStatusOfLatestSubscription(): Promise<ResponseWithHttpCode | null>
└── function getStatusForCurrentSubscription(): Promise<ResponseWithHttpCode | null>
└── function getStatusOfLatestSubscriptionForProvider(
provider: string | null
): Promise<ResponseWithHttpCode | null>
Функции запроса статуса подписки:
function getStatusOfLatestSubscription()— статус последней подписки профиля;function getStatusForCurrentSubscription()— статус подписки для текущего токена/провайдера;function getStatusOfLatestSubscriptionForProvider()— статус последней подписки по провайдеру. Если указанnull, то используется провайдер текущего токена.
function getStatusOfLatestSubscription(): Promise<ResponseWithHttpCode | null>
Функция получения статуса последней подписки профиля. Возвращает ResponseWithHttpCode | null, содержащий response?.profile?.subscription — последнюю созданную подписку в профиле. Если такой подписки не существует, будет передан null.
Пример использования:
const result = await AltcraftSDK.getStatusOfLatestSubscription();
function getStatusForCurrentSubscription(): Promise<ResponseWithHttpCode | null>
Функция получения статуса подписки для текущего токена/провайдера. Возвращает ResponseWithHttpCode | null, содержащий response?.profile?.subscription — подписку, найденную по текущему push-токену и провайдеру. Если такой подписки не существует, будет передан null.
Пример использования:
const result = await AltcraftSDK.getStatusForCurrentSubscription();
function getStatusOfLatestSubscriptionForProvider(provider: string | null): Promise<ResponseWithHttpCode | null>
Функция получения статуса последней подписки по провайдеру. Возвращает ResponseWithHttpCode | null, содержащий response?.profile?.subscription — последнюю созданную подписку с указанным провайдером. Если провайдер не указан (provider = null), используется провайдер текущего токена. Если такой подписки не существует, будет передан null.
Пример использования:
const result = await AltcraftSDK.getStatusOfLatestSubscriptionForProvider(null);
Ниже представлен пример извлечения данных о профиле, подписке и категориях из ответа функций получения статуса. Данный подход актуален для всех функций получения статуса:
Данные из функций получения статуса
import AltcraftSDK from '@altcraft/react-native-sdk';
async function readStatus(): Promise<void> {
const result = await AltcraftSDK.getStatusForCurrentSubscription();
if (!result) return;
const httpCode = result.httpCode ?? null;
const response = result.response ?? null;
const error = response?.error ?? null;
const errorText = response?.errorText ?? null;
const profile = response?.profile ?? null;
const subscription = profile?.subscription ?? null;
const cats = subscription?.cats ?? null;
}
Управление push-токенами провайдеров
AltcraftSDK
|
└─ // Получить текущие данные токена устройства
├── function getPushToken(): Promise<TokenData | null>
|
| // Сохранить/обновить токен вручную для конкретного провайдера
└── function setPushToken(provider: string, token: string | null): Promise<void>
Функции для работы с токеном провайдера в SDK:
function setPushToken()— установка push-токена устройства и провайдера;function getPushToken()— получение текущего push-токена.
setPushToken(provider, token)
Функция предназначена для установки push-токена устройства и провайдера.
- В React Native не передаётся
context— сохранение и хранение токена выполняется на нативной стороне SDK. token: null— означает очистку токена для указанного провайдера.
Пример использования:
import AltcraftSDK from '@altcraft/react-native-sdk';
await AltcraftSDK.setPushToken('FCM', token);
Пример передачи токена при получении нового токена:
import AltcraftSDK from '@altcraft/react-native-sdk';
async function onNewToken(provider: string, token: string) {
await AltcraftSDK.setPushToken(provider, token);
}
getPushToken()
Функция возвращает текущие данные push-токена устройства и провайдера в виде TokenData.
Формат возвращаемых данных:
-
TokenData— объект с полями:provider: stringtoken: string
Если токен недоступен — будет возвращено null.
Пример использования:
import AltcraftSDK from '@altcraft/react-native-sdk';
const tokenData = await AltcraftSDK.getPushToken();
Пример запроса получения данных push-токена:
import AltcraftSDK from '@altcraft/react-native-sdk';
async function readPushToken() {
const data = await AltcraftSDK.getPushToken();
const provider = data?.provider ?? null;
const token = data?.token ?? null;
return { provider, token };
}
Регистрация и передача push-уведомлений в SDK
В нативном коде
Для настрой ки работы с push-уведомлениями (получение и передача в SDK) в React Native воспользуйтесь инструкциями нативных SDK:
Android:
- Подключение push-провайдеров
- Подготовка SDK к работе с push-провайдерами
- Передача push-уведомлений в SDK
Обратите внимание, в RN-проекте на Android точка входа приложения — MainApplication : Application(), ReactApplication. Используйте MainApplication для регистрации провайдеров , а не отдельный Application-класс.
iOS:
- Подключение push-провайдеров
- Настройка AppDelegate приложения
- Подготовка NSE
- Работа с push-уведомлениями
npm-библиотека Altcraft @altcraft/react-native-sdk уже включает нативные SDK. Все нативные классы доступны в коде iOS- и Android-приложения сразу после установки пакета. Не подключайте SDK дополнительно через Gradle или Swift Package Manager.
В React Native (только для Android)
В Android входящие push-уведомления можно получать в React-части приложения, используя одного из провайдеров:
- FCM (Firebase Cloud Messaging):
@react-native-firebase/appи@react-native-firebase/messaging - HMS (Huawei Mobile Services):
@hmscore/react-native-hms-push
FCM
Установите необходимые зависимости:
npm i @react-native-firebase/app @react-native-firebase/messaging
# или
yarn add @react-native-firebase/app @react-native-firebase/messaging
Обработка push-уведомлений через FCM происходит следующим образом:
Background push
import messaging from '@react-native-firebase/messaging';
messaging().setBackgroundMessageHandler(async (rm) => {
console.log('altcraft_lib push background');
const payload = RemoteMessagetoStringMap(rm?.data);
if (payload) {
AltcraftSDK.takePush(payload);
}
});
Foreground push
function registerFCMForegroundPush(): void {
if (fcmFg || Platform.OS !== 'android') return;
fcmFg = true;
messaging().onMessage(async (rm) => {
console.log('altcraft_lib push foreground');
const payload = RemoteMessagetoStringMap(rm?.data);
if (payload) {
AltcraftSDK.takePush(payload);
}
});
}
Для передачи push-уведомления в SDK используется метод:
AltcraftSDK.takePush(message: Record<string, string>): void
где message — данные push-уведомления, предварительно преобразованные из RemoteMessage в формат Record<string, string>.
Данный подход можно объединить с использованием нативного push-сервиса FirebaseMessagingService: уведомления могут обрабатываться нативно и параллельно передаваться в React Native/Altcraft SDK для бизнес-логики.
HMS
Установите необходимые зависимости:
npm i @hmscore/react-native-hms-push
# или
yarn add @hmscore/react-native-hms-push
Обработка push-уведомлений через HMS происходит следующим образом:
Background push
import { HmsPushMessaging, RNRemoteMessage } from '@hmscore/react-native-hms-push';
HmsPushMessaging.setBackgroundMessageHandler(async (dataMessage) => {
console.log('altcraft_lib push background');
const payload = new RNRemoteMessage(dataMessage).getDataOfMap();
if (payload) {
AltcraftSDK.takePush(payload);
}
});
Foreground push
import { Platform } from 'react-native';
import { HmsPushEvent, RNRemoteMessage } from '@hmscore/react-native-hms-push';
let hmsFg = false;
function registerHMSForegroundPush(): void {
if (hmsFg || Platform.OS !== 'android') return;
hmsFg = true;
HmsPushEvent.onRemoteMessageReceived((dataMessage) => {
console.log('altcraft_lib push foreground');
const payload = new RNRemoteMessage(dataMessage).getDataOfMap();
if (payload) {
AltcraftSDK.takePush(payload);
}
});
}
Для передачи push-уведомления в SDK используется метод:
AltcraftSDK.takePush(message: Record<string, string>): void
где message — данные push-уведомления, предварительно преобразованные из RemoteMessage в формат Record<string, string>.
Данный подход можно объединить с использованием нативного push-сервиса HmsMessageService: уведомления могут обрабатываться нативно и параллельно передаваться в React Native/Altcraft SDK для бизнес-логики.
Мобильные события
// Функция объекта AltcraftSDK (React Native)
AltcraftSDK
└── function mobileEvent(
sid: string,
eventName: string,
sendMessageId?: string | null,
payload?: Record<string, unknown> | null,
matching?: Record<string, unknown> | null,
matchingType?: string | null,
profileFields?: Record<string, unknown> | null,
subscription?: Subscription | null,
utm?: UTM | null
): void