Firebase՝ push, Remote Config և Crashlytics

01Ինչպես են իրականում աշխատում push ծանուցումները

Ձեր սերվերը երբեք ուղղակիորեն չի խոսում հեռախոսի հետ։ iOS-ում օպերացիոն համակարգը մեկ կապ է պահում APNs-ի (Apple Push Notification service) հետ, Android-ում Google Play services-ը մեկ կապ է պահում FCM-ի հետ։ Երբ ձեր հավելվածը մեկնարկում է, այն OS-ից խնդրում է device token՝ այս սարքի վրա այս հավելվածի հասցեն, և ուղարկում այն ձեր backend-ին՝ կապված օգտատիրոջ հետ։ Օգտատիրոջը ծանուցելու համար ձեր backend-ը կանչում է FCM HTTP v1 API-ն այդ token-ով․ FCM-ը Android-ում առաքում է ուղղակիորեն, իսկ iOS-ի համար փոխանցում է APNs-ին (դուք մեկ անգամ APNs auth key եք վերբեռնում Firebase)։ Token-ները փոխվում են՝ վերատեղադրումից, վերականգնումից հետո կամ պարբերաբար, ուստի լսեք token refresh-ը և թարմացրեք backend-ը։ Երբ FCM-ը token-ը հայտնում է որպես unregistered, ջնջեք այն։ Մեկ օգտատեր կարող է ունենալ մի քանի սարք, ուստի մեկ օգտատիրոջ համար պահեք շատ token-ներ։

• Device token՝ հավելվածի մեկ տեղադրման հասցե, ոչ թե մարդու
• APNs auth key (.p8)՝ վերբեռնված Firebase iOS առաքման համար
• FCM HTTP v1 API՝ service account-ով․ legacy API-ն այլևս չկա
• Topic-ներ՝ մեկ հաղորդագրություն ուղարկել շատ subscriber-ների (օր․՝ 'promo-hy')

02Թույլտվություններ և token-ի ստացում

iOS-ին ծանուցումներ ցույց տալու համար միշտ պետք է օգտատիրոջ թույլտվությունը, իսկ Android-ին Android 13-ից (API 33) պետք է POST_NOTIFICATIONS runtime թույլտվությունը։ Եթե օգտատերը սեղմում է «Don't allow», սովորաբար այլևս չեք կարող հարցնել․ նա պետք է գնա Settings։ Ուստի հարցրեք այն պահին, երբ արժեքն ակնհայտ է՝ առաջին պատվերից հետո («Ծանուցե՞լ, երբ ձեր սուրճը պատրաստ լինի»), ոչ թե առաջին էկրանին։ Համակարգային dialog-ից առաջ ցույց տվեք կարճ բացատրություն հավելվածի ներսում։ iOS-ն աջակցում է նաև provisional authorization, որը ծանուցումները լուռ առաքում է notification center՝ առանց prompt-ի։ React Native Firebase-ով flow-ը հետևյալն է՝ խնդրել թույլտվություն, ստանալ token-ը, ուղարկել այն ձեր API-ին պլատֆորմի և հավելվածի տարբերակի հետ և subscribe անել token refresh-ին։

1import { getMessaging, requestPermission, getToken, onTokenRefresh,
2  AuthorizationStatus } from "@react-native-firebase/messaging";
3import { PermissionsAndroid, Platform } from "react-native";
4 
5export async function registerForPush(api: Api) {
6  const messaging = getMessaging();
7  if (Platform.OS === "android" && Platform.Version >= 33) {
8    await PermissionsAndroid.request("android.permission.POST_NOTIFICATIONS");
9  }
10  const status = await requestPermission(messaging);
11  if (status === AuthorizationStatus.DENIED) return;
12 
13  const token = await getToken(messaging);
14  await api.post("/devices", { token, platform: Platform.OS });
15  onTokenRefresh(messaging, (t) => api.post("/devices", { token: t, platform: Platform.OS }));
16}

03Notification և data հաղորդագրություններ, foreground և tap-եր

FCM հաղորդագրությունը կարող է կրել notification բլոկ (title, body), data բլոկ (ձեր սեփական key-value string-ները) կամ երկուսն էլ։ Notification հաղորդագրությունները OS-ը ավտոմատ ցուցադրում է, երբ հավելվածը background-ում է կամ փակված է։ Միայն data պարունակող հաղորդագրություններն առաքվում են ձեր կոդին, որը որոշում է, թե ինչ անել․ iOS-ում դրանք background push-եր են, որոնք համակարգը կարող է throttle անել կամ ուշացնել, ուստի երբեք մի հենվեք դրանց վրա օգտատիրոջը տեսանելի ծանուցումների համար։ Երբ հավելվածը foreground-ում է, OS-ը default-ով banner ցույց չի տալիս․ դուք այն ստանում եք onMessage-ում և որոշում՝ ցույց տալ in-app toast, թարմացնել badge կամ ցուցադրել local notification Notifee-ով։ Tap-երը մշակեք երեք վիճակում՝ foreground, background (onNotificationOpenedApp) և cold start (getInitialNotification)։ Data-ի մեջ դրեք deep-link route և navigate արեք դրանով։

1{
2  "message": {
3    "token": "DEVICE_TOKEN",
4    "notification": { "title": "Order ready", "body": "Your latte is waiting at the counter" },
5    "data": { "type": "order_status", "orderId": "1042", "link": "app://orders/1042" },
6    "android": { "priority": "high", "notification": { "channel_id": "orders" } },
7    "apns": { "payload": { "aps": { "sound": "default" } } }
8  }
9}

04Հուսալի ուղարկում backend-ից

Push-երն ուղարկեք queue worker-ից, ոչ թե HTTP հարցման ներսում․ պատվերի կարգավիճակի փոփոխությունը job է գրում, և worker-ը կանչում է FCM-ը retry-ներով և backoff-ով։ Օգտագործեք Firebase Admin SDK-ն կամ HTTP v1 endpoint-ը service-account credential-ով, որը պահվում է որպես գաղտնիք սերվերում, երբեք հավելվածում։ Յուրաքանչյուր արշավ կամ հաղորդագրություն պահեք նաև ձեր սեփական տվյալների բազայում, որպեսզի հավելվածը կարողանա ցույց տալ in-app inbox․ push-երի հասնելը երաշխավորված չէ, և օգտատերերը մաքրում են դրանք։ Հարգեք լռության ժամերը և օգտատիրոջ նախընտրությունները (պատվերի թարմացումները՝ միացված, մարքեթինգը՝ անջատված), իսկ Android-ում ստեղծեք առանձին notification channel-ներ, որպեսզի օգտատերերը կարողանան անջատել ակցիաները՝ չկորցնելով պատվերի թարմացումները։ Մաքրեք այն token-ները, որոնք FCM-ը վերադարձնում է որպես unregistered։ Զանգվածային արշավների համար օգտագործեք topic-ներ կամ batch ուղարկումներ և պլանավորեք դրանք ձեր սեփական job համակարգով։

05Remote Config՝ force update, maintenance, feature flag-եր

Remote Config-ը Firebase-ում պահվող key-value պարամետրերի հավաքածու է, որը հավելվածը ստանում է runtime-ում։ Default-ները ներառում եք հավելվածի ներսում, մեկնարկի ժամանակ fetch և activate եք անում խելամիտ minimum fetch interval-ով և արժեքները կարդում որպես boolean-ներ, թվեր կամ string-ներ։ Պայմանները թույլ են տալիս թիրախավորել ըստ պլատֆորմի, հավելվածի տարբերակի, երկրի կամ օգտատերերի տոկոսի։ Երեք կիրառություն ինքնին արդարացնում են իրենց։ Force update՝ պահեք min_supported_version ըստ պլատֆորմի․ եթե տեղադրված տարբերակն ավելի ցածր է, ցույց տվեք արգելափակող էկրան store-ի հղումով, ինչը էական է, երբ հին հավելվածը կկոտրվեր նոր API-ի դեմ։ Maintenance mode՝ դրոշակ, որը միգրացիաների ժամանակ ցույց է տալիս բարեհամբույր էկրան։ Feature flag-եր և աստիճանական rollout՝ միացրեք նոր checkout-ը օգտատերերի 10%-ի համար, հետևեք Crashlytics-ին, ապա անցեք 100%-ի։ Տրամաբանությունը պահեք անվտանգ, եթե fetch-ը ձախողվի․ հավելվածը պետք է աշխատի default-ներով։

1import { getRemoteConfig, setDefaults, setConfigSettings,
2  fetchAndActivate, getValue } from "@react-native-firebase/remote-config";
3import { Platform } from "react-native";
4import DeviceInfo from "react-native-device-info";
5 
6export async function checkAppGate() {
7  const rc = getRemoteConfig();
8  await setDefaults(rc, { min_version_ios: "1.0.0", min_version_android: "1.0.0", maintenance: false });
9  await setConfigSettings(rc, { minimumFetchIntervalMillis: 15 * 60 * 1000 });
10  await fetchAndActivate(rc).catch(() => undefined); // offline: use cached/defaults
11 
12  const key = Platform.OS === "ios" ? "min_version_ios" : "min_version_android";
13  if (getValue(rc, "maintenance").asBoolean()) return "maintenance";
14  if (isLower(DeviceInfo.getVersion(), getValue(rc, key).asString())) return "force_update";
15  return "ok";
16}

06Crashlytics և Analytics

Crashlytics-ը հավաքում է native crash-երը և, React Native Firebase-ով, ձեր գրանցած JavaScript սխալները՝ խմբավորված ըստ issue-ի և կապված հավելվածի տարբերակի ու սարքի հետ։ Համոզվեք, որ symbol ֆայլերը (dSYM-ներ iOS-ում, mapping ֆայլեր Android-ում) վերբեռնվում են build-ի ժամանակ, այլապես stack trace-երը մնում են անընթեռնելի։ Ավելացրեք կոնտեքստ՝ սահմանեք ոչ անձնական user ID, ռիսկային քայլերից առաջ log արեք breadcrumb-ներ (վճարման սկիզբ, վճարումից վերադարձ) և գրանցեք կարևոր API ձախողումներից մշակված սխալները։ Հետևեք crash-free users տոկոսին ըստ release-ի․ staged rollout-ի ժամանակ այն ձեր ազդանշանն է կանգ առնելու։ Analytics-ը գրանցում է event-ներ, ինչպիսիք են screen_view, add_to_cart, begin_checkout և purchase։ Նախքան կոդ գրելը սահմանեք event-ների փոքր պլան՝ հետևողական անուններով, խուսափեք անձնական տվյալներ ուղարկելուց և հարգեք համաձայնությունը՝ անջատեք հավաքումը, մինչև օգտատերը համաձայնի, որտեղ օրենքը դա պահանջում է։

07Առաքման ներքին մեխանիզմը․ priority, TTL, collapsing և Doze

Առաքումը ձևավորվում է էներգիայի կառավարմամբ։ Android-ի Doze mode-ը անգործ հեռախոսների համար network-ի հասանելիությունը խմբավորում է batch-երով․ normal priority FCM հաղորդագրությունները սպասում են maintenance window-ի, իսկ high priority հաղորդագրությունները կարող են արթնացնել սարքը։ Google-ը կարող է իջեցնել այն հավելվածների առաջնահերթությունը, որոնց high priority հաղորդագրությունները չեն հանգեցնում տեսանելի notification-ի, ուստի high priority օգտագործեք միայն այն alert-ների համար, որոնք օգտատերը տեսնում է։ iOS-ում apns-priority 10-ը նշանակում է առաքել հիմա, իսկ 5-ը՝ առաքել հարմար պահին․ background (content-available) push-երը պետք է օգտագործեն priority 5 և սահմանափակվում են համակարգի կողմից։ Յուրաքանչյուր հաղորդագրություն ունի կյանքի տևողություն․ android.ttl-ը և apns-expiration header-ը որոշում են, թե որքան ժամանակ է ծառայությունը փորձում offline սարքին հասնել։ Collapse key-ը (Android) կամ apns-collapse-id-ն (iOS) հին չառաքված հաղորդագրությունները փոխարինում են ամենանորով, ուստի online վերադարձող հեռախոսը ցույց է տալիս մեկ «զամբյուղը թարմացվել է» հաղորդագրություն, ոչ թե տասը։ Payload-ները պահեք փոքր․ FCM-ը մերժում է մոտ 4 KB-ից մեծ հաղորդագրությունները։

1{
2  "message": {
3    "token": "DEVICE_TOKEN",
4    "data": { "type": "cart_sync", "cartId": "c_981" },
5    "android": { "priority": "normal", "ttl": "3600s", "collapse_key": "cart" },
6    "apns": {
7      "headers": {
8        "apns-priority": "5",
9        "apns-push-type": "background",
10        "apns-collapse-id": "cart"
11      },
12      "payload": { "aps": { "content-available": 1 } }
13    }
14  }
15}

08Մեծ ծավալով ուղարկում․ batching, սխալներ և quota-ներ

Firebase Admin SDK-ն sendEachForMulticast-ով մեկ կանչով ուղարկում է մինչև 500 token-ից բաղկացած ցուցակ և վերադարձնում մեկ արդյունք յուրաքանչյուր token-ի համար՝ նույն հերթականությամբ։ Դասակարգեք յուրաքանչյուր ձախողում։ registration-token-not-registered-ը նշանակում է, որ հավելվածը ջնջվել է կամ token-ը rotate է եղել․ ջնջեք այն։ invalid-argument-ը նշանակում է, որ ձեր payload-ը սխալ է․ շտկեք կոդը, retry մի արեք։ Quota-exceeded-ը (HTTP 429) և unavailable կամ internal սխալները (503, 500) ժամանակավոր են․ retry արեք exponential backoff-ով և հարգեք Retry-After header-ը։ Գոյություն ունեն project-ի մակարդակի quota-ներ, ուստի մեծ campaign-ները պետք է անցնեն queue-ով, որը կարգավորում է ուղարկման տեմպը, այլ ոչ թե loop-ով, որը ամեն ինչ միանգամից կրակում է։ Տեմպի կարգավորումը պաշտպանում է նաև ձեր սեփական backend-ը․ եթե 200,000 մարդ նույն վայրկյանին ստանան promotion, շատերը նույն րոպեին կբացեն հավելվածը։

1import { getMessaging } from "firebase-admin/messaging";
2 
3export async function sendToUser(tokens: string[], title: string, body: string, link: string) {
4  const res = await getMessaging().sendEachForMulticast({
5    tokens, // up to 500 per call
6    notification: { title, body },
7    data: { link },
8  });
9 
10  const dead = res.responses
11    .map((r, i) => (r.error?.code === "messaging/registration-token-not-registered" ? tokens[i] : null))
12    .filter((t): t is string => t !== null);
13 
14  await removeTokens(dead); // keep the token table clean
15  return { sent: res.successCount, failed: res.failureCount };
16}

09Notification-ների գաղտնիություն և անվտանգություն

Notification-ը ցուցադրվում է lock screen-ին, արտացոլվում է ժամացույցներին և երբեմն կարդացվում բարձրաձայն, ուստի դրա տեքստին վերաբերվեք որպես հրապարակային։ Երբեք title-ում կամ body-ում մի դրեք միանգամյա կոդեր, մնացորդներ, առողջության մանրամասներ կամ ամբողջական հասցեներ․ գրեք «Ձեր պատվերը թարմացում ունի» և մանրամասները ցույց տվեք հավելվածի ներսում՝ authentication-ից հետո։ iOS-ում Notification Service Extension-ը կարող է decrypt անել encrypt արված payload-ը կամ ներբեռնել rich media՝ նախքան ցուցադրումը (mutable-content), ինչը թույլ է տալիս Apple-ի և Google-ի սերվերներով ուղարկել ավելի քիչ զգայուն տվյալներ։ Push-եր ուղարկող service account-ի credential-ը հզոր է․ տվեք նրան միայն անհրաժեշտ Firebase Cloud Messaging role-երը, պահեք secret store-ում և rotate արեք։ Device token-ները secret չեն, բայց դրանք օգտատիրոջ հետ կապված անձնական տվյալներ են․ unlink արեք դրանք sign-out-ի ժամանակ և ջնջեք, երբ account-ը ջնջվում է։

10Remote Config-ի ներքին կառուցվածքը և թակարդները

Remote Config-ը client-side կոնֆիգուրացիա է, ոչ թե անվտանգության սահման․ արժեքները ներբեռնվում են սարք և այնտեղ կարող են կարդացվել կամ փոփոխվել, ուստի երբեք մի պահեք դրանում secret-ներ և մի օգտագործեք այն թույլտվություններ տալու համար՝ access-ը պետք է պարտադրի սերվերը։ SDK-ն cache է անում արժեքները և սահմանափակում fetch-երը․ default minimum fetch interval-ը 12 ժամ է, ուստի այն իջեցրեք գիտակցաբար և խուսափեք յուրաքանչյուր էկրանում fetch անելուց։ Որոշեք, թե ինչպես են արժեքներն ակտիվանում․ fetchAndActivate-ը գործարկման ժամանակ պարզ է, բայց կարող է փոխել UI-ը դրա հայտնվելուց հետո․ background-ում fetch անելը և հաջորդ գործարկմանը ակտիվացնելը խուսափում է flicker-ից։ Real-time Remote Config-ը կարող է փոփոխություններ push անել աշխատող հավելվածներին, երբ ձեզ պետք են արագ kill-switch-եր։ Տոկոսային պայմանները կայուն են յուրաքանչյուր app installation-ի համար, ուստի նույն օգտատերը մնում է նույն խմբում։ Յուրաքանչյուր publish ստեղծում է template version, որը կարող եք rollback անել, ինչը օգտակար է, երբ վատ արժեքը ինչ-որ բան է կոտրում։