Настройка push-уведомлений по геозоне 1С-Битрикс

Настройка push-уведомлений по геозоне 1С-Битрикс

Push-уведомления по геозоне — частный случай геофенсинга с фокусом именно на канале доставки. Задача: когда пользователь оказывается в заданном радиусе от точки, он получает push на телефон. Разбираем, как это реализуется с серверной стороны Битрикса.

Стек доставки push

Для мобильных push-уведомлений работают два канала:

• FCM (Firebase Cloud Messaging) — Android и iOS (через Firebase APNs proxy)
• APNs (Apple Push Notification service) — iOS напрямую

Для веб-сайта без мобильного приложения существуют Web Push (стандарт W3C), но они требуют открытого браузера или поддержки Service Worker и не работают в iOS Safari до iOS 16.4.

Битрикс имеет встроенный модуль push.sender — но он предназначен для Битрикс24 и Push & Pull сервера. Для кастомных push в мобильном приложении используете FCM напрямую из PHP.

Регистрация и хранение токенов устройств

Перед отправкой push нужно получить device token пользователя. Приложение при первом запуске запрашивает разрешение и получает токен от FCM/APNs, затем отправляет его на сервер.

Эндпоинт для регистрации токена (/local/ajax/register-token.php):

$userId      = $USER->GetID();
$deviceToken = $data['token'];
$platform    = $data['platform']; // 'android' или 'ios'

// Сохраняем в HL-инфоблок DeviceTokens
\Local\Push\DeviceTokenTable::add([
    'UF_USER_ID'  => $userId,
    'UF_TOKEN'    => $deviceToken,
    'UF_PLATFORM' => $platform,
    'UF_UPDATED'  => new \Bitrix\Main\Type\DateTime(),
]);

Один пользователь может иметь несколько токенов (телефон + планшет). Токены устаревают — FCM возвращает ошибку NotRegistered, по которой нужно удалять токен из базы.

Триггер по геозоне

Геозонное событие приходит с мобильного приложения (логику нативного геофенсинга см. в статье про geofencing-уведомления). Серверная часть получает событие и ищет все активные токены пользователя:

$tokens = \Local\Push\DeviceTokenTable::getList([
    'filter' => ['=UF_USER_ID' => $userId, '=UF_ACTIVE' => true],
    'select' => ['UF_TOKEN', 'UF_PLATFORM'],
])->fetchAll();

foreach ($tokens as $token) {
    \Local\Push\Sender::send(
        $token['UF_TOKEN'],
        $token['UF_PLATFORM'],
        $zone['UF_PUSH_TITLE'],
        $zone['UF_PUSH_BODY'],
        ['zone_id' => $zoneId, 'action' => 'open_promo']
    );
}

Отправка через FCM HTTP v1 API

Google переходит с legacy FCM API на HTTP v1 (OAuth2). Пример отправки одного push:

namespace Local\Push;

class Sender {
    public static function send(
        string $token,
        string $platform,
        string $title,
        string $body,
        array $data = []
    ): bool {
        $accessToken = self::getOAuthToken(); // OAuth2 через Service Account JSON

        $message = [
            'message' => [
                'token' => $token,
                'notification' => [
                    'title' => $title,
                    'body'  => $body,
                ],
                'data' => array_map('strval', $data),
            ],
        ];

        $http = new \Bitrix\Main\Web\HttpClient();
        $http->setHeader('Authorization', 'Bearer ' . $accessToken);
        $http->setHeader('Content-Type', 'application/json');
        $response = $http->post(
            'https://fcm.googleapis.com/v1/projects/' . FCM_PROJECT_ID . '/messages:send',
            json_encode($message)
        );

        $result = json_decode($response, true);
        return isset($result['name']); // name присутствует при успехе
    }
}

Для getOAuthToken() используется Google Client Library или собственная реализация JWT-подписи с Service Account.

Кастомный звук и иконка

Для Android-уведомлений можно задать канал уведомлений (Notification Channel), звук и иконку через секцию android в payload FCM. Для iOS — через секцию apns. Эти параметры задаются при разработке мобильного приложения, серверная часть только передаёт значения.

Мониторинг доставки

FCM HTTP v1 возвращает результат немедленно, но это лишь подтверждение принятия на обработку, не факт доставки. Для отслеживания открытий уведомлений нужна аналитика на стороне приложения (Firebase Analytics или собственный эндпоинт).