Лучшие практики управления регистрационными токенами FCM

Если вы используете API FCM для программного создания запросов на отправку, со временем вы можете обнаружить, что тратите ресурсы впустую, отправляя сообщения на неактивные устройства с устаревшими токенами регистрации. Это может повлиять на данные о доставке сообщений, отслеживаемые в консоли Firebase или экспортируемые в BigQuery, что проявляется в резком (но не фактическом) снижении скорости доставки. В этом руководстве рассматриваются некоторые меры, которые можно предпринять для обеспечения эффективного таргетинга сообщений и корректной отчётности о доставке.

Устаревшие и просроченные регистрационные токены

Устаревшие регистрационные токены — это токены, связанные с неактивными устройствами, которые не подключались к FCM более месяца. С течением времени вероятность повторного подключения устройства к FCM становится всё меньше и меньше. Отправка сообщений и разветвление тем для этих устаревших токенов вряд ли когда-либо будут доставлены.

Существует несколько причин, по которым токен может устареть. Например, устройство, с которым он связан, может быть потеряно, уничтожено или помещено на хранение и забыто.

Когда срок неактивности устаревших токенов достигает 270 дней, FCM считает их просроченными . После истечения срока действия токена FCM помечает его как недействительный и отклоняет отправку на него. Однако в редких случаях, когда устройство снова подключается к приложению и приложение открывается, FCM выпускает новый токен для экземпляра приложения.

Основные рекомендации

Существует ряд фундаментальных правил, которым следует следовать в любом приложении, использующем API FCM для программного формирования запросов на отправку. Основные рекомендации:

  • Получайте регистрационные токены из FCM и храните их на своём сервере. Важная роль сервера — отслеживать токены каждого клиента и поддерживать актуальный список активных токенов. Мы настоятельно рекомендуем реализовать временную метку токена в вашем коде и на ваших серверах и регулярно её обновлять.
  • Поддерживайте актуальность токенов и удаляйте устаревшие токены. Помимо удаления токенов, которые FCM больше не считает действительными, вы можете отслеживать другие признаки устаревания токенов и удалять их заблаговременно. В этом руководстве рассматриваются некоторые варианты достижения этой цели.

Извлечение и хранение регистрационных токенов

При первом запуске приложения FCM SDK генерирует регистрационный токен для экземпляра клиентского приложения. Этот токен необходимо включать в запросы на целевую отправку через API или добавлять в подписки на темы для таргетинга.

Мы настоятельно рекомендуем вашему приложению получать этот токен при первом запуске и сохранять его на сервере приложения вместе с меткой времени . Эта метка времени должна быть реализована в вашем коде и на ваших серверах, так как она не предоставляется FCM SDK.

Кроме того, важно сохранять токен на сервере и обновлять временную метку при каждом его изменении, например, когда:

  • Приложение восстановлено на новом устройстве.
  • Пользователь удаляет или переустанавливает приложение.
  • Пользователь очищает данные приложения
  • Приложение снова станет активным после того, как FCM истечет срок действия его текущего токена.

Пример: хранение токенов и временных меток в Cloud Firestore

Например, вы можете использовать Cloud Firestore для хранения токенов в коллекции fcmTokens . Каждый идентификатор документа в коллекции соответствует идентификатору пользователя, а сам документ хранит текущий регистрационный токен и его последнюю обновленную временную метку. Используйте функцию set , как показано в этом примере на Kotlin:

    /**
     * Persist token to third-party servers.
     *
     * Modify this method to associate the user's FCM registration token with any server-side account
     * maintained by your application.
     *
     * @param token The new token.
     */
    private fun sendTokenToServer(token: String?) {
        // If you're running your own server, call API to send token and today's date for the user

        // Example shown below with Firestore
        // Add token and timestamp to Firestore for this user
        val deviceToken = hashMapOf(
            "token" to token,
            "timestamp" to FieldValue.serverTimestamp(),
        )
        // Get user ID from Firebase Auth or your own server
        Firebase.firestore.collection("fcmTokens").document("myuserid")
            .set(deviceToken)
    }
MyFirebaseMessagingService.kt

Всякий раз, когда токен извлекается, он сохраняется в Cloud Firestore путем вызова sendTokenToServer :

    /**
     * Called if the FCM registration token is updated. This may occur if the security of
     * the previous token had been compromised. Note that this is called when the
     * FCM registration token is initially generated so this is where you would retrieve the token.
     */
    override fun onNewToken(token: String) {
        Log.d(TAG, "Refreshed token: $token")

        // If you want to send messages to this application instance or
        // manage this apps subscriptions on the server side, send the
        // FCM registration token to your app server.
        sendTokenToServer(token)
    }
MyFirebaseMessagingService.kt

        var token = Firebase.messaging.token.await()

        // Check whether the retrieved token matches the one on your server for this user's device
        val preferences = this.getPreferences(Context.MODE_PRIVATE)
        val tokenStored = preferences.getString("deviceToken", "")
        lifecycleScope.launch {
            if (tokenStored == "" || tokenStored != token)
            {
                // If you have your own server, call API to send the above token and Date() for this user's device

                // Example shown below with Firestore
                // Add token and timestamp to Firestore for this user
                val deviceToken = hashMapOf(
                    "token" to token,
                    "timestamp" to FieldValue.serverTimestamp(),
                )

                // Get user ID from Firebase Auth or your own server
                Firebase.firestore.collection("fcmTokens").document("myuserid")
                    .set(deviceToken).await()
            }
        }

MainActivity.kt

Поддерживайте актуальность токенов и удаляйте устаревшие токены

Определить, актуален токен или нет, не всегда просто. Чтобы охватить все случаи, следует установить пороговое значение, при котором токены считаются устаревшими. По умолчанию FCM считает токен устаревшим, если экземпляр его приложения не подключался в течение месяца. Любой токен старше одного месяца, скорее всего, относится к неактивному устройству; в противном случае активное устройство обновило бы свой токен.

В зависимости от вашего варианта использования один месяц может быть слишком коротким или слишком длинным, поэтому вам нужно самостоятельно определить критерии, которые подходят именно вам.

Обнаружение недействительных ответов токенов от бэкэнда FCM

Обязательно распознавайте недействительные ответы токенов от FCM и удаляйте из системы все заведомо недействительные или просроченные токены регистрации. При использовании API HTTP v1 эти сообщения об ошибках могут указывать на то, что ваш запрос на отправку был направлен на недействительные или просроченные токены:

  • UNREGISTERED (HTTP 404)
  • INVALID_ARGUMENT (HTTP 400)

Если вы уверены, что полезная нагрузка сообщения верна, и получаете один из этих ответов для целевого токена, вы можете безопасно удалить запись об этом токене, так как он больше никогда не будет действителен. Например, чтобы удалить недействительные токены из Cloud Firestore , вы можете развернуть и запустить функцию, подобную следующей:

    // Registration token comes from the client FCM SDKs
    const registrationToken = 'YOUR_REGISTRATION_TOKEN';

    const message = {
    data: {
        // Information you want to send inside of notification
    },
    token: registrationToken
    };

    // Send message to device with provided registration token
    getMessaging().send(message)
    .then((response) => {
        // Response is a message ID string.
    })
    .catch((error) => {
        // Delete token for user if error code is UNREGISTERED or INVALID_ARGUMENT.
        if (errorCode == "messaging/registration-token-not-registered") {
            // If you're running your own server, call API to delete the
            token for the user

            // Example shown below with Firestore
            // Get user ID from Firebase Auth or your own server
            Firebase.firestore.collection("fcmTokens").document(user.uid).delete()
        }
    });

FCM вернёт ответ о недействительном токене только в том случае, если срок действия токена истёк более 270 дней или если клиент явно отменил регистрацию. Если вам нужно более точно отслеживать устаревание в соответствии с вашими собственными определениями, вы можете заблаговременно удалять устаревшие токены регистрации .

Регулярно обновляйте токены

Мы рекомендуем вам периодически извлекать и обновлять все регистрационные токены на вашем сервере. Для этого вам необходимо:

  • Добавьте логику приложения в клиентское приложение для получения текущего токена с помощью соответствующего вызова API (например, token(completion): для платформ Apple или getToken() для Android), а затем отправьте текущий токен на сервер приложения для хранения (с меткой времени). Это может быть ежемесячное задание, настроенное для охвата всех клиентов или токенов.
  • Добавьте серверную логику для обновления временной метки токена через регулярные интервалы, независимо от того, изменился ли токен.

Пример логики Android для обновления токенов с помощью WorkManager см. в разделе Управление токенами Cloud Messaging в блоге Firebase.

Независимо от выбранного вами графика обновления, обязательно периодически обновляйте токены. Частота обновления раз в месяц обеспечивает оптимальный баланс между влиянием на заряд батареи и обнаружением неактивных регистрационных токенов. Выполняя это обновление, вы также гарантируете, что любое устройство, ставшее неактивным, обновит свою регистрацию, когда снова станет активным. Нет смысла обновлять токены чаще, чем раз в неделю.

Удалить устаревшие регистрационные токены

Перед отправкой сообщений на устройство убедитесь, что временная метка регистрационного токена устройства находится в пределах заданного периода устаревания. Например, вы можете реализовать Cloud Functions for Firebase для ежедневной проверки, чтобы убедиться, что временная метка находится в пределах заданного периода устаревания, например, const EXPIRATION_TIME = 1000 * 60 * 60 * 24 * 30; а затем удалить устаревшие токены:

exports.pruneTokens = functions.pubsub.schedule('every 24 hours').onRun(async (context) => {
  // Get all documents where the timestamp exceeds is not within the past month
  const staleTokensResult = await admin.firestore().collection('fcmTokens')
      .where("timestamp", "<", Date.now() - EXPIRATION_TIME)
      .get();
  // Delete devices with stale tokens
  staleTokensResult.forEach(function(doc) { doc.ref.delete(); });
});
index.js

Отменить подписку на устаревшие токены из тем

Если вы используете темы, вам также может потребоваться отменить регистрацию устаревших токенов в темах, на которые они подписаны. Это включает в себя два шага:

  1. Ваше приложение должно повторно подписываться на темы раз в месяц и при каждом изменении регистрационного токена. Это решение самовосстановления, при котором подписки автоматически восстанавливаются при возобновлении активности приложения.
  2. Если экземпляр приложения неактивен в течение одного месяца (или вашего собственного окна устаревания), вам следует отписать его от тем с помощью Firebase Admin SDK, чтобы удалить токен для сопоставления тем из бэкэнда FCM .

Преимущество этих двух шагов заключается в том, что ваши разветвления будут происходить быстрее, поскольку будет меньше устаревших токенов для разветвления, а устаревшие экземпляры приложений будут автоматически переподписываться, как только они снова станут активными.

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

Чтобы получить наиболее точную картину доставки сообщений, лучше всего отправлять их только в активно используемые приложения. Это особенно важно, если вы регулярно отправляете сообщения в темы с большим количеством подписчиков; если часть этих подписчиков фактически неактивны, со временем это может существенно повлиять на статистику доставки.

Прежде чем направлять сообщения токену, учтите следующее:

  • Указывают ли данные Google Analytics, собранные в BigQuery, или другие сигналы отслеживания на то, что токен активен?
  • Были ли предыдущие попытки доставки постоянно неудачными в течение определенного периода времени?
  • Обновлялся ли регистрационный токен на ваших серверах в течение последнего месяца?
  • Сообщает ли API данных FCM о высоком проценте сбоев доставки сообщений из-за droppedDeviceInactive для устройств Android?

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