Публичный API SDK

class AltcraftSDK

Точка входа в SDK. Все методы статические. JWT и push token provider регистрируются нативно (Application.onCreate на Android, AppDelegate на iOS) и не доступны через Dart API.

AltcraftSDK
// ---- Инициализация ----
├─ static Future<void> initialize(AltcraftConfig config)
├─ static Future<void> clear()
├─ static Future<bool> requestNotificationPermission()
└─ static void unlockInitialOperationsInThisSession()

// ---- Подписка на push ----
├─ static void pushSubscribe({bool? sync, ...})
├─ static void pushSuspend({bool? sync, ...})
├─ static void pushUnSubscribe({bool? sync, ...})
└─ static Future<ResponseWithHttpCode?> unSuspendPushSubscription()

// ---- Статус подписки ----
├─ static Future<ResponseWithHttpCode?> getStatusOfLatestSubscription()
├─ static Future<ResponseWithHttpCode?> getStatusForCurrentSubscription()
└─ static Future<ResponseWithHttpCode?> getStatusOfLatestSubscriptionForProvider(String? provider)

// ---- События SDK ----
├─ static Stream<SdkEvent> subscribeToEvents()
└─ static Future<void> unsubscribeFromEvents()

// ---- Мобильные события и профиль ----
├─ static void mobileEvent({required String sid, required String eventName, ...})
└─ static void updateProfileFields({Map<String, dynamic>? profileFields, bool? skipTriggers})

// ---- Push-токены ----
├─ static Future<TokenData?> getPushToken()
├─ static Future<void> setPushToken(String provider, String? token)
├─ static Future<void> forcedTokenUpdate()
├─ static Future<void> deleteDeviceToken(String provider)
└─ static Future<void> changePushProviderPriorityList(List<String> priorityList)

// ---- Push-уведомления (Android) ----
├─ static void takePush(Map<String, String> message)
├─ static Future<bool> isAltcraftPush(Map<String, String> message)
├─ static void deliveryEvent(Map<String, String>? message, String? messageUID)
└─ static void openEvent(Map<String, String>? message, String? messageUID)

// ---- Native storage (iOS / Android) ----
├─ static void setAppGroup(String? groupName)
└─ static void setUserDefaultsValue(String? suiteName, String key, dynamic value)

---

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

initialize(config)

static Future<void> initialize(AltcraftConfig config)

Инициализирует Altcraft SDK с заданной конфигурацией. Вызывается один раз при старте приложения, до runApp().

Параметр	Тип	Описание
config	AltcraftConfig	Объект конфигурации SDK (обязательный).

Возвращает: Future<void> — завершается, когда нативный SDK завершил инициализацию.

Выбрасывает: AltcraftException при ошибке инициализации на нативной стороне.

import 'package:altcraft_sdk/altcraft_sdk.dart';
import 'package:flutter/widgets.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AltcraftSDK.initialize(
    AltcraftConfig(
      apiUrl: 'https://pxl-example.altcraft.com',
      appInfo: const AppInfo(
        appID: '1:000000000000:android:0000000000000000',
        appIID: '00000000-0000-4000-8000-000000000000',
        appVer: '1.0.0',
      ),
      providerPriorityList: ['android-firebase'],
    ),
  );

  runApp(const MyApp());
}

clear()

static Future<void> clear()

Полная очистка данных SDK: локальная база данных, хранилище токенов, отмена всех фоновых задач.

Возвращает: Future<void>. Выбрасывает: AltcraftException при ошибке.

requestNotificationPermission()

static Future<bool> requestNotificationPermission()

Запрашивает разрешение на отправку уведомлений (Android 13+). На iOS разрешения настраиваются нативно.

Возвращает: Future<bool> — true, если разрешение предоставлено, false — если отказано.

final bool granted = await AltcraftSDK.requestNotificationPermission();

if (granted) {
  AltcraftSDK.pushSubscribe(sync: true);
}

unlockInitialOperationsInThisSession()

static void unlockInitialOperationsInThisSession()

Разрешает переинициализацию push-модуля в текущей сессии (Android). Используется, когда требуется повторная инициализация push-компонентов без перезапуска приложения.

---

Подписка на push

pushSubscribe() / pushSuspend() / pushUnSubscribe()

static void pushSubscribe({
  bool? sync,
  Map<String, dynamic>? profileFields,
  Map<String, dynamic>? customFields,
  List<dynamic>? cats,
  bool? replace,
  bool? skipTriggers,
})

static void pushSuspend({...})
static void pushUnSubscribe({...})

Метод	Статус	Коды событий
pushSubscribe()	subscribed	230 (успех), 430 (ошибка), 530 (ретрай)
pushSuspend()	suspended	231 (успех), 431 (ошибка), 531 (ретрай)
pushUnSubscribe()	unsubscribed	232 (успех), 432 (ошибка), 532 (ретрай)

Все три метода имеют одинаковую сигнатуру.

Параметр	Тип	Описание
sync	bool?	true — синхронный запрос (результат через событие SDK). false — асинхронный.
profileFields	Map<String, dynamic>?	Поля профиля (системные и опциональные).
customFields	Map<String, dynamic>?	Пользовательские поля подписки (только скаляры).
cats	List<dynamic>?	Категории подписки (name + active).
replace	bool?	При true подписки других профилей с тем же push-токеном переводятся в unsubscribed.
skipTriggers	bool?	При true профиль игнорируется в триггерах рассылок и сценариев.

Возвращает: void (fire-and-forget). Результат доступен через события SDK.

AltcraftSDK.pushSubscribe(
  sync: true,
  profileFields: const {'_fname': 'Ivan', '_lname': 'Petrov'},
  cats: const [{'name': 'news', 'active': true}],
);

unSuspendPushSubscription()

static Future<ResponseWithHttpCode?> unSuspendPushSubscription()

Возобновляет приостановленную подписку. Используется для LogIn/LogOut-переходов между профилями.

Алгоритм:

1. Ищет подписки с тем же push-токеном, не относящиеся к профилю текущего JWT;
2. Меняет их статус с subscribed на suspended;
3. Меняет статус подписок профиля текущего JWT с suspended на subscribed;
4. Возвращает данные профиля текущего JWT (или null, если профиль не найден).

Возвращает: Future<ResponseWithHttpCode?> — данные профиля или null.

final ResponseWithHttpCode? result =
    await AltcraftSDK.unSuspendPushSubscription();

if (result == null) {
  AltcraftSDK.pushSubscribe();
}

---

Статус подписки

getStatusOfLatestSubscription()

static Future<ResponseWithHttpCode?> getStatusOfLatestSubscription()

Возвращает статус последней подписки профиля. response?.profile?.subscription содержит последнюю созданную подписку. Если подписок нет — null.

getStatusForCurrentSubscription()

static Future<ResponseWithHttpCode?> getStatusForCurrentSubscription()

Возвращает статус подписки для текущего push-токена и провайдера. response?.profile?.subscription содержит подписку, найденную по текущему токену. Если подписки нет — null.

getStatusOfLatestSubscriptionForProvider(provider)

static Future<ResponseWithHttpCode?> getStatusOfLatestSubscriptionForProvider(
  String? provider,
)

Возвращает статус последней подписки по указанному провайдеру. Если provider = null, используется провайдер текущего токена.

Параметр	Тип	Описание
provider	String?	Идентификатор провайдера (например, android-firebase).

Все три метода возвращают Future<ResponseWithHttpCode?> и выбрасывают AltcraftException при ошибке.

---

События SDK

subscribeToEvents()

static Stream<SdkEvent> subscribeToEvents()

Возвращает поток событий SDK. События доставляются из нативного SDK через EventChannel (com.altcraft/events). Каждый вызов создаёт независимый Stream.

Возвращает: Stream<SdkEvent>.

unsubscribeFromEvents()

static Future<void> unsubscribeFromEvents()

Останавливает доставку событий из нативного SDK. Для повторной подписки вызовите subscribeToEvents().

Возвращает: Future<void>.

import 'dart:async';
import 'package:altcraft_sdk/altcraft_sdk.dart';

StreamSubscription<SdkEvent>? subscription;

void startListening() {
  subscription = AltcraftSDK.subscribeToEvents().listen(
    (SdkEvent event) {
      print('[${event.type}] ${event.function}: ${event.message}');
    },
  );
}

Future<void> stopListening() async {
  await subscription?.cancel();
  subscription = null;
  await AltcraftSDK.unsubscribeFromEvents();
}

---

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

mobileEvent()

static void mobileEvent({
  required String sid,
  required String eventName,
  String? sendMessageId,
  Map<String, dynamic>? payload,
  Map<String, dynamic>? matching,
  String? matchingType,
  Map<String, dynamic>? profileFields,
  Map<String, dynamic>? subscription,
  Map<String, dynamic>? utm,
})

Регистрирует мобильное событие Altcraft.

Параметр	Тип	Описание
sid	String	Идентификатор пикселя (обязательный).
eventName	String	Имя события (обязательный).
sendMessageId	String?	SMID отправленного сообщения.
payload	Map<String, dynamic>?	Данные события. Сериализуются через MethodChannel.
matching	Map<String, dynamic>?	Данные матчинга (например, {'email': 'user@example.com'}).
matchingType	String?	Тип матчинга.
profileFields	Map<String, dynamic>?	Поля профиля (JWT-сценарии).
subscription	Map<String, dynamic>?	Подписка для канала. Используйте Subscription.toMap().
utm	Map<String, dynamic>?	UTM-метки.

Возвращает: void.

AltcraftSDK.mobileEvent(
  sid: 'pixel-000000000000000000000000',
  eventName: 'purchase',
  payload: const {
    'orderId': 'A-1001',
    'amount': 3990,
    'currency': 'RUB',
  },
);

updateProfileFields()

static void updateProfileFields({
  Map<String, dynamic>? profileFields,
  bool? skipTriggers,
})

Обновляет поля профиля на сервере.

Параметр	Тип	Описание
profileFields	Map<String, dynamic>?	Карта полей профиля для обновления.
skipTriggers	bool?	При true профиль игнорируется в триггерах рассылок и сценариев.

Возвращает: void.

---

Push-токены

getPushToken()

static Future<TokenData?> getPushToken()

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

Возвращает: Future<TokenData?> — объект TokenData или null, если токен недоступен.

Выбрасывает: AltcraftException при ошибке.

setPushToken(provider, token)

static Future<void> setPushToken(String provider, String? token)

Устанавливает или очищает push-токен для указанного провайдера. Сохранение выполняется на нативной стороне SDK.

Параметр	Тип	Описание
provider	String	Идентификатор провайдера (например, android-firebase, ios-apns).
token	String?	Значение токена. null — очистка токена.

forcedTokenUpdate()

static Future<void> forcedTokenUpdate()

Принудительное обновление push-токена: удаляет текущий токен и запрашивает новый у провайдера.

deleteDeviceToken(provider)

static Future<void> deleteDeviceToken(String provider)

Удаляет токен устройства для указанного провайдера.

Параметр	Тип	Описание
provider	String	Идентификатор провайдера.

changePushProviderPriorityList(priorityList)

static Future<void> changePushProviderPriorityList(List<String> priorityList)

Изменяет список приоритетов push-провайдеров и инициирует обновление токена.

Параметр	Тип	Описание
priorityList	List<String>	Новый список приоритетов. Индекс 0 — самый приоритетный.

await AltcraftSDK.changePushProviderPriorityList(
  ['android-firebase', 'android-huawei', 'android-rustore'],
);

Все методы выбрасывают AltcraftException при ошибке.

---

Push-уведомления (Android)

takePush(message)

static void takePush(Map<String, String> message)

Передаёт входящий push payload в SDK. Работает на Android. На iOS обработка push выполняется нативно.

Параметр	Тип	Описание
message	Map<String, String>	Данные push-уведомления, преобразованные в Map<String, String>.

isAltcraftPush(message)

static Future<bool> isAltcraftPush(Map<String, String> message)

Проверяет, относится ли push-сообщение к Altcraft.

Параметр	Тип	Описание
message	Map<String, String>	Payload push-сообщения.

Возвращает: Future<bool> — true, если сообщение принадлежит Altcraft.

deliveryEvent(message, messageUID)

static void deliveryEvent(Map<String, String>? message, String? messageUID)

Ручная регистрация доставки push-уведомления (Android).

Параметр	Тип	Описание
message	Map<String, String>?	Data payload уведомления.
messageUID	String?	Идентификатор сообщения.

Можно передать только message (SDK извлечёт UID из payload) или только messageUID. Если оба null — событие не зарегистрируется.

openEvent(message, messageUID)

static void openEvent(Map<String, String>? message, String? messageUID)

Ручная регистрация открытия push-уведомления (Android). Параметры и правила передачи идентичны deliveryEvent().

---

Native storage (iOS / Android)

setAppGroup(groupName)

static void setAppGroup(String? groupName)

Устанавливает App Group для UserDefaults на iOS. Определяет пространство, разделяемое между основным приложением и Notification Service Extension.

Параметр	Тип	Описание
groupName	String?	Идентификатор App Group (например, group.altcraft.example).

setUserDefaultsValue(suiteName, key, value)

static void setUserDefaultsValue(String? suiteName, String key, dynamic value)

Сохраняет значение в нативном хранилище: UserDefaults на iOS, SharedPreferences на Android. Значение value преобразуется в строку через toString().

Параметр	Тип	Описание
suiteName	String?	Имя App Group / suite (iOS). На Android игнорируется.
key	String	Ключ хранилища.
value	dynamic	Значение (преобразуется в String).

class AltcraftConfig

class AltcraftConfig {
  final String apiUrl;
  final String? rToken;
  final AppInfo? appInfo;
  final List<String>? providerPriorityList;
  final bool? enableLogging;

  // -------- ANDROID-ONLY --------
  final int? icon;
  final List<String>? pushReceiverModules;
  final String? pushChannelName;
  final String? pushChannelDescription;
}

Класс конфигурации Altcraft SDK. Хранит базовый API URL и опциональные параметры.

Поле	Тип	Обязательный	Описание
apiUrl	String	Да	Базовый URL Altcraft API.
rToken	String?	Нет	Ролевой токен (идентифицирует ресурс/БД/аккаунт).
appInfo	AppInfo?	Нет	Метаданные приложения (ID, IID, версия).
providerPriorityList	List<String>?	Нет	Приоритет провайдеров push. Индекс 0 — самый приоритетный.
enableLogging	bool?	Нет	Включает/отключает ведение логов.
icon	int?	Нет	ID ресурса иконки уведомлений (Android).
pushReceiverModules	List<String>?	Нет	Пакеты модулей с переопределённым PushReceiver (Android).
pushChannelName	String?	Нет	Имя канала push-уведомлений (Android).
pushChannelDescription	String?	Нет	Описание канала push-уведомлений (Android).

AppInfo:

class AppInfo {
  final String appID;
  final String appIID;
  final String appVer;
}

Поле	Тип	Описание
appID	String	Идентификатор приложения (Firebase App ID).
appIID	String	Идентификатор установки (Firebase Instance ID).
appVer	String	Версия приложения.

Data Classes

SdkEvent

class SdkEvent {
  final String function;
  final int? code;
  final String message;
  final String type;
  final Map<String, dynamic>? value;
  final String? timestamp;
}

Универсальное событие SDK, доставляется в Dart через Stream (под капотом EventChannel).

Поле	Тип	Описание
function	String	Имя функции SDK, вызвавшая событие.
code	int?	Код события (см. таблицу кодов).
message	String	Сообщение события.
type	String	event, error, retryError.
value	Map<String, dynamic>?	Дополнительные данные (например, response_with_http_code).
timestamp	String?	Временная метка в формате yyyy-MM-dd HH:mm:ss.SSS.

---

TokenData

class TokenData {
  final String provider;
  final String token;
}

Данные push-токена провайдера устройства.

Поле	Тип	Описание
provider	String	Идентификатор провайдера (например, android-firebase, ios-apns).
token	String	Значение push-токена.

---

ResponseWithHttpCode

class ResponseWithHttpCode {
  final int httpCode;
  final Map<String, dynamic>? response;
}

Обёртка ответа API с HTTP-кодом. Поле response содержит:

Поле	Тип	Описание
error	int?	Внутренний код ошибки сервера (0 — нет ошибок).
errorText	String?	Текст ошибки.
profile	Map<String, dynamic>?	Данные профиля и подписки.

Вложенная структура profile:

Поле	Тип	Описание
id	String?	Идентификатор профиля.
status	String?	Статус профиля.
isTest	bool?	Флаг тестового режима.
subscription	Map<String, dynamic>?	Данные подписки.

Вложенная структура subscription:

Поле	Тип	Описание
subscription_id	String?	Идентификатор подписки у провайдера.
hash_id	String?	Хэш подписки.
provider	String?	Провайдер подписки.
status	String?	Статус подписки (subscribed, suspended, unsubscribed).
fields	Map<String, dynamic>?	Системные и пользовательские поля.
cats	List<dynamic>?	Категории подписки.

---

CategoryData

class CategoryData {
  final String? name;
  final String? title;
  final bool? steady;
  final bool? active;
}

Категория подписки.

Поле	Тип	Описание
name	String?	Название категории.
title	String?	Заголовок (заполняется при получении данных подписки).
steady	bool?	Флаг стабильности (заполняется при получении данных подписки).
active	bool?	Статус активности категории.

При отправке push-запроса используйте только name и active.

---

Subscription

class Subscription {
  final String type;
  final int resourceId;
  final String? status;
  final int? priority;
  final String? email;
  final String? phone;
  final String? provider;
  final String? subscriptionId;
  final Map<String, dynamic>? customFields;
  final List<dynamic>? cats;
  final Map<String, dynamic>? ccData;
}

Модель подписки для мобильных событий. Factory-конструкторы:

// Email
Subscription.email({required int resourceId, required String email, ...})

// SMS
Subscription.sms({required int resourceId, required String phone, ...})

// Push
Subscription.push({required int resourceId, required String provider, required String subscriptionId, ...})

// CcData (Telegram, WhatsApp, Viber, Notify)
Subscription(type: 'cc_data', resourceId: 10, ccData: {'channel': 'telegram_bot', 'chat_id': '123456'})

Метод toMap() сериализует подписку в Map<String, dynamic> для передачи в mobileEvent().

---

UTM

class UTM {
  final String? source;
  final String? medium;
  final String? campaign;
  final String? content;
  final String? keyword;
  final String? temp;
}

Контейнер UTM-параметров для атрибуции мобильных событий. В mobileEvent() передаётся как Map<String, dynamic>.

ActionFieldBuilder

class ActionFieldBuilder {
  final String key;

  Map<String, dynamic> set(dynamic value);
  Map<String, dynamic> unset(dynamic value);
  Map<String, dynamic> incr(dynamic value);
  Map<String, dynamic> add(dynamic value);
  Map<String, dynamic> delete(dynamic value);
  Map<String, dynamic> upsert(dynamic value);
}

ActionFieldBuilder actionField(String key);

Builder для структурированного управления полями профиля. Производит карту, совместимую с нативным SDK.

Метод	Описание
set(value)	Установить поле в заданное значение.
unset(value)	Удалить значение поля.
incr(value)	Увеличить числовое поле на заданное значение.
add(value)	Добавить значение в поле-множество/массив.
delete(value)	Удалить значение из поля-множества/массива.
upsert(value)	Установить, если поле отсутствует; обновить, если существует.

import 'package:altcraft_sdk/altcraft_sdk.dart';

final profileFields = <String, dynamic>{
  ...actionField('_fname').set('Ivan'),
  ...actionField('login_count').incr(1),
  ...actionField('visited_pages').add('/settings'),
};

AltcraftSDK.updateProfileFields(profileFields: profileFields);

Exceptions

AltcraftException

class AltcraftException implements Exception {
  final String code;
  final String message;
  final Object? details;
}

Исключение, выбрасываемое SDK при ошибках вызова методов через MethodChannel.

Поле	Тип	Описание
code	String	Код ошибки.
message	String	Сообщение об ошибке.
details	Object?	Дополнительные данные.

SdkNotInitializedException

class SdkNotInitializedException extends AltcraftException

Выбрасывается при вызове методов SDK до инициализации. Код: SDK_NOT_INITIALIZED.

try {
  await AltcraftSDK.getStatusOfLatestSubscription();
} on SdkNotInitializedException {
  print('SDK not initialized yet');
} on AltcraftException catch (e) {
  print('SDK error (${e.code}): ${e.message}');
}

Constants

Провайдеры push-уведомлений:

Провайдер	Значение
FCM (Android)	android-firebase
HMS (Android)	android-huawei
RuStore (Android)	android-rustore
APNS (iOS)	ios-apns
FCM (iOS)	ios-firebase
HMS (iOS)	ios-huawei

Статусы подписки:

Статус	Значение
Подписан	subscribed
Отписан	unsubscribed
Приостановлен	suspended