Функционал 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-токенами провайдеров

подсказка

На нативной стороне приложения можно использовать функции, указанные в статьях для соответствующих платформ (для Android, для iOS)

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/altcraft-react-native-sdk';
// или
// import AltcraftSDK from '@altcraft-react-native-sdk/...';

await AltcraftSDK.setPushToken('FCM', token);

Пример передачи токена при получении нового токена:

import AltcraftSDK from '@altcraft/altcraft-react-native-sdk';
// или
// import AltcraftSDK from '@altcraft-react-native-sdk/...';

async function onNewToken(provider: string, token: string) {
  await AltcraftSDK.setPushToken(provider, token);
}

getPushToken()

Функция возвращает текущие данные push-токена устройства и провайдера в виде TokenData.

Формат возвращаемых данных:

TokenData — объект с полями:
- provider: string
- token: string

Если токен недоступен — будет возвращено null.

Пример использования:

import AltcraftSDK from '@altcraft/altcraft-react-native-sdk';
// или
// import AltcraftSDK from '@altcraft-react-native-sdk/...';

const tokenData = await AltcraftSDK.getPushToken();

Пример запроса получения данных push-токена:

import AltcraftSDK from '@altcraft/altcraft-react-native-sdk';
// или
// 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:

Обратите внимание, в RN-проекте на Android точка входа приложения — MainApplication : Application(), ReactApplication. Используйте MainApplication для регистрации провайдеров , а не отдельный Application-класс.

iOS:

Важно

npm-библиотека Altcraft @altcraft/react-native-sdk уже включает нативные SDK. Все нативные классы доступны в коде iOS- и Android-приложения сразу после установки пакета. Не подключайте SDK дополнительно через Gradle, CocoaPods или 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

Для регистрации мобильного события используйте функцию mobileEvent() из AltcraftSDK. Она имеет следующие параметры:

sid: string

Обязательный: Да
Описание: Строковый идентификатор пикселя, к которому привязываются мобильные события.

eventName: string

Обязательный: Да
Описание: Имя мобильного события.

sendMessageId: string | null

Обязательный: Нет
Описание: SMID-идентификатор отправленного сообщения (если событие связано с конкретной рассылкой).

payload: Record<string, unknown> | null

Обязательный: Нет
Описание: Данные события — карта со строковыми ключами. В RN-бридже значения сериализуются в string:

string —> как есть
number / boolean / bigint —> String(value)
object / array —> JSON.stringify(value)
null / undefined —> ключ не передаётся (поле удаляется из payload)

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

Несериализуемые объекты (например, Date без преобразования, кастомные классы, функции) будут переданы как строка через String(value) или могут привести к некорректным данным. Рекомендуется передавать JSON-совместимые значения.

matching: Record<string, unknown> | null

Обязательный: Нет
Описание: Карта, в которую можно передавать значения с типами и идентификаторами матчинга (например, {"email": "user@example.com"}). В RN-бридже значения сериализуются в string по тем же правилам, что и payload.

matchingType: string | null

Обязательный: Нет
Описание: Тип матчинга.

profileFields: Record<string, unknown> | null

Обязательный: Нет
Описание: Поля профиля — карта со строковыми ключами. В RN-бридже значения сериализуются в string по тем же правилам, что и payload.

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

Параметр profileFields используется только при работе с JWT-авторизацией.

subscription: Subscription | null

Обязательный: Нет
Описание: Параметр добавления подписки для выбранного канала.

Значение параметра — одна из реализаций union-типа Subscription:

EmailSubscription — email-подписка
SmsSubscription — SMS-подписка
PushSubscription — push-подписка
CcDataSubscription — подписка в Telegram, Whatsapp, Viber, Notify.

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

Параметр subscription используется только при работе с JWT-авторизацией.

Общие поля подписки (для всех реализаций)

Поле	Тип	Обязательный	Описание
`type`	`string`	Да	Тип канала (дискриминатор).
`resource_id`	`number`	Да	Идентификатор ресурса/источника подписки.
`status`	`string \| null`	Нет	Статус подписки (например, активна/приостановлена).
`priority`	`number \| null`	Нет	Приоритет доставки.
`custom_fields`	`{ [key: string]: string } \| null`	Нет	Пользовательские поля подписки.
`cats`	`string[] \| null`	Нет	Категории подписки.

Варианты подписки

EmailSubscription (type = "email")

Поле	Тип	Обязательный	Описание
`resource_id`	`number`	Да	ID ресурса Altcraft
`email`	`string`	Да	Адрес электронной почты

SmsSubscription (type = "sms")

Поле	Тип	Обязательный	Описание
`resource_id`	`number`	Да	ID ресурса Altcraft
`phone`	`string`	Да	Номер телефона в международном формате

PushSubscription (type = "push")

Поле	Тип	Обязательный	Описание
`resource_id`	`number`	Да	ID ресурса Altcraft
`provider`	`string`	Да	Провайдер (например, `"android-firebase"`)
`subscription_id`	`string`	Да	Уникальный идентификатор подписки у провайдера

CcDataSubscription (type = "cc_data")

Поле	Тип	Обязательный	Описание
`resource_id`	`number`	Да	ID ресурса Altcraft
`channel`	`string`	Да	Один из: `"telegram_bot"`, `"whatsapp"`, `"viber"`, `"notify"`
`cc_data`	`{ [key: string]: string }`	Да	Канал-специфичные данные (например, chat ID, номер, токены)

utm: UTM | null

Обязательный: Нет
Описание: UTM-метки. Передаются структурой UTM, где каждый вид UTM — отдельное поле:

    export type UTM = {
      campaign?: string | null;
      content?: string | null;
      keyword?: string | null;
      medium?: string | null;
      source?: string | null;
      temp?: string | null;
    };

Примеры использования

import AltcraftSDK from '@altcraft/react-native-sdk';

AltcraftSDK.mobileEvent('your sid', 'app_open');

Передача данных через payload

    AltcraftSDK.mobileEvent(
      'your sid',
      'purchase',
      null,
      {
        orderId: 'A-1001',
        amount: 3990,
        currency: 'RUB',
        items: [{ sku: 'sku-1', qty: 2 }],
      }
    );

Передача UTM-меток

    AltcraftSDK.mobileEvent(
      'your sid',
      'app_install',
      null,
      null,
      null,
      null,
      null,
      null,
      {
        campaign: 'your campaign utm',
        content: 'your content utm',
        keyword: 'your keyword utm',
        medium: 'your medium utm',
        source: 'your source utm',
        temp: 'your temp utm',
      }
    );

Передача matching / matchingType

    AltcraftSDK.mobileEvent(
      'your sid',
      'profile_update',
      null,
      { source: 'settings' },
      { email: 'user@example.com' },
      'email'
    );

*Передача subscription (JWT)

    import type { PushSubscription } from '@altcraft/react-native-sdk';
    
    const sub: PushSubscription = {
      type: 'push',
      resource_id: 10,
      provider: 'android-firebase',
      subscription_id: 'provider-sub-id',
      status: 'active',
      priority: 1,
      custom_fields: { utm: 'your utm tag' },
      cats: ['promo', 'news'],
    };
    
    AltcraftSDK.mobileEvent(
      'your sid',
      'jwt_bind_subscription',
      null,
      null,
      null,
      null,
      null,
      sub,
      null
    );

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

При передаче subscription в RN-бридже часть полей сериализуется в строковый формат (например, custom_fields и cats передаются как JSON-строки). Передавайте JSON-совместимые значения.

Получение событий SDK в приложении

В React Native события SDK передаются из нативного слоя через NativeEventEmitter. В приложении может быть только один активный подписчик на события SDK.

События эмитятся под именем AltcraftSdkEvent. Каждое событие, получаемое в JS, имеет следующий формат:

export type SdkEvent = {
  function: string;                 // имя функции SDK
  code: number | null;              // код события
  message: string;                  // сообщение события
  type: 'event' | 'error' | 'retryError';
  value?: Record<string, unknown> | null; // дополнительная нагрузка
};

Типы событий:

event — информационные события и успешные операции;
error — ошибки выполнения;
retryError — ошибки операций, для которых SDK выполняет автоматический повтор.

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

Для подписки используйте функцию subscribeToEvents.

При повторной подписке предыдущий подписчик автоматически удаляется.

import AltcraftSDK, { subscribeToEvents } from 'altcraft-react-native-sdk';

subscribeToEvents((event) => {
  switch (event.type) {
    case 'event':
      // обработка успешного события
      break;

    case 'error':
      // обработка ошибки
      break;

    case 'retryError':
      // обработка ошибки с автоповтором
      break;
  }
});

Отписка от событий

Для прекращения получения событий используйте unsubscribeFromEvent.

import { unsubscribeFromEvent } from 'altcraft-react-native-sdk';

unsubscribeFromEvent();

После вызова подписчик удаляется, и события SDK больше не доставляются в JavaScript.

Список всех событий SDK

Список событий

Код	Описание
200	SDK configuration is installed
201	push provider set
202	received a notification unrelated to the Altcraft Platform
203	received Altcraft push notification
204	push is posted
205	SDK data has been cleared
206	waiting for SDK initialization to complete
207	waiting for push token update to complete
220	receiver override event
230	subscribe request succeeded
231	push suspend request succeeded
232	push unsubscribed request succeeded
233	push update request succeeded
234	push unsuspend request succeeded
235	profile status request succeeded
236	push event delivered successfully
237	mobile event delivered successfully
401	the configuration is not set
402	userTag is null. It is impossible to identify the user
404	SDK initialization timeout has expired
405	mobile event parts is null
422	unsuspend request data is null
423	profile request data is null
430	subscribe request failed
431	suspend request failed
432	unsubscribed request failed
433	update request failed
434	unsuspend request failed
435	status request failed
436	push event delivery failed
437	mobile event request failed
450	push data is null
451	uid in the push data is null or empty, it is impossible to send a push event to the server
452	error uploading the notification image
453	couldn't create notification
454	foreground info is null
455	the notification channel has not been created
471	invalid provider. Available - android-firebase, android-huawei, android-rustore
472	invalid customFields: not all values are primitives
480	subscribe retry limit reached (request removed from DB)
484	push event retry limit reached (request removed from DB)
485	mobile event retry limit reached (request removed from DB)
501	config data is null
502	current push token is null
503	userTag is null. It is impossible to identify the user
504	no permission to send notifications
505	no internet connection, retry when connection is restored
506	failed to update the push token. The subscription request was rejected
520	push subscribe request data is null
521	token update request data is null
524	push event request data is null
525	mobile event request data is null
529	common data is null
530	subscribe request failed (retryable)
531	token update request failed (retryable)
534	push event delivery failed (retryable)
535	mobile event delivery failed (retryable)
540	JWT token is null
541	matching mode is null
542	JWT payload exceeds allowed size (16 KB limit): input rejected to prevent DoS
543	JWT does not contain a payload
544	auth data is null
545	matching claim does not contain a matching ID
560	response data is null

Дополнительные функции SDK

Очистка данных SDK

AltcraftSDK.clear();

Функция позволяет выполнить очистку данных SDK и отменить работу всех фоновых задач, которые ожидают выполнения.

Ручная регистрация push-событий

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

Эти функции применяются только в том случае, если вы реализуете собственную логику обработки уведомлений и не передаёте их в SDK автоматически.

Android

В React Native доступны функции ручной регистрации push-событий на стороне JS:

deliveryEvent(message?: Record<string, string> | null, messageUID?: string | null) — регистрация доставки уведомления;
openEvent(message?: Record<string, string> | null, messageUID?: string | null) — регистрация открытия уведомления.

Параметры:

message: Record<string, string> | null — data payload уведомления в виде словаря строк.
messageUID: string | null — идентификатор сообщения.

Правила передачи:

можно передать только message (SDK возьмёт идентификатор сообщения из payload, если он в нём присутствует);
можно передать только messageUID (если payload недоступен, но идентификатор известен);
если оба параметра null — событие не будет зарегистрировано корректно (нет данных для идентификации сообщения).

iOS

Ручная регистрация push-событий SDK на стороне React Native не реализуется. Если требуется ручная регистрация событий, выполните её в нативной части приложения.

См. инструкцию для iOS (ручная регистрация push-событий).

Работа со статусами подписки​

Изменение статуса подписки​

Запрос статуса подписки​

Управление push-токенами провайдеров​

Регистрация и передача push-уведомлений в SDK​

В нативном коде​

В React Native (только для Android)​

Мобильные события​

Получение событий SDK в приложении​

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

Отписка от событий​

Список всех событий SDK​

Дополнительные функции SDK​

Очистка данных SDK​

Ручная регистрация push-событий​

Android​

iOS​

Работа со статусами подписки

Изменение статуса подписки

Запрос статуса подписки

Управление push-токенами провайдеров

Регистрация и передача push-уведомлений в SDK

В нативном коде

В React Native (только для Android)

Мобильные события

Получение событий SDK в приложении

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

Отписка от событий

Список всех событий SDK

Дополнительные функции SDK

Очистка данных SDK

Ручная регистрация push-событий

Android

iOS