Intégration de notifications Push

Cet article de référence explique comment configurer les notifications push iOS pour le SDK Swift de Braze.

Les notifications push vous permettent d’envoyer des notifications depuis votre appli lorsque des événements importants se produisent. Vous pouvez envoyer une notification push lorsque vous avez de nouveaux messages instantanés à envoyer, des alertes d’actualité à envoyer ou le dernier épisode de l’émission télévisée préférée de votre utilisateur prêt à être téléchargé pour un visionnage hors ligne. Les notifications push peuvent également être silencieuses, n’étant utilisées que pour mettre à jour l’interface de votre appli ou déclencher des travaux en arrière-plan.

Les notifications push sont idéales pour le contenu sporadique, mais immédiatement important, alors que le délai entre les récupérations en arrière-plan peut ne pas être acceptable. Les notifications push peuvent également être beaucoup plus efficaces que la récupération en arrière-plan, car votre application ne démarre que si nécessaire.

Les notifications push sont limitées en débit, n’ayez donc pas peur d’en envoyer autant que votre application en a besoin. iOS et les serveurs du service de notification push (APN) d’Apple contrôleront la fréquence à laquelle elles sont délivrées, et vous n’aurez pas d’ennuis si vous en envoyez trop. Si vos notifications push sont limitées, elles peuvent être retardées jusqu’à la prochaine fois que l’appareil envoie un paquet persistant ou reçoit une autre notification.

Configuration initiale

Étape 1 : Téléchargez votre certificat d’APN

Avant de pouvoir envoyer une notification push iOS à l’aide de Braze, vous devez fournir votre fichier de notifications push .p8 fourni par Apple. Comme décrit dans la documentation du développeur Apple :

1. Dans votre compte de développeur Apple, allez dans Certificats, identifiants et profils.
2. Sous Clés, sélectionnez Tous et cliquez sur le bouton d’ajout (+) dans le coin supérieur droit.
3. Sous Description de la clé, saisissez un nom unique pour la clé de signature.
4. Sous Services clés, cochez la case Service de notification push d’Apple (APN), puis cliquez sur Continuer. Cliquez sur Confirmer.
5. Notez l’ID de la clé. Cliquez sur Télécharger pour générer et télécharger la clé. Assurez-vous d’enregistrer le fichier téléchargé dans un endroit sécurisé, car vous ne pouvez pas le télécharger plus d’une fois.
6. Dans Braze, allez dans Paramètres > Paramètres des applications et téléchargez le fichier .p8 sous Certificat de notification push Apple. Vous pouvez charger votre certificat de notifications push de développement ou de production. Pour tester les notifications push une fois que votre application est en ligne dans l’App Store, il est recommandé de créer un espace de travail distinct pour la version de développement de votre application.
7. Lorsque vous y êtes invité, saisissez l’ID d’offre groupée, l’ID de clé et l’ID d’équipe de votre application, puis cliquez sur Enregistrer.

Étape 2 : Activer les fonctionnalités de notification push

Dans Xcode, ajoutez la capacité Notifications push à l’aide du volet Signature et capacités pour la cible d’appli principale.

Intégration automatique de la poussée

Le SDK Swift propose une approche basée uniquement sur la configuration pour automatiser le traitement des notifications à distance reçues de Braze. Cette approche est la manière la plus simple d’intégrer les notifications push et est recommandée pour la plupart des clients.

Pour activer l’intégration automatique des notifications push, définissez la propriété automation de la configuration push sur true :

• swift
• objectif-c

1
2
let configuration = Braze.Configuration(apiKey: "{YOUR-BRAZE-API-KEY}", endpoint: "{YOUR-BRAZE-API-ENDPOINT}")
configuration.push.automation = true

1
2
BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:@"{YOUR-BRAZE-API-KEY}" endpoint:@"{YOUR-BRAZE-API-ENDPOINT}"];
configuration.push.automation = [[BRZConfigurationPushAutomation alloc] initEnablingAllAutomations:YES];

Cela demande au SDK de :

• Enregistrer votre application pour les notifications push dans le système.
• Demander l’autorisation/permission de la notification push lors de l’initialisation.
• Fournir dynamiquement des implémentations pour les méthodes de délégation du système liées à la notification push.

Remplacer des configurations individuelles

Pour un contrôle plus précis, chaque étape d’automatisation peut être activée ou désactivée individuellement :

• swift
• objectif-c

1
2
3
// Enable all automations and disable the automatic notification authorization request at launch.
configuration.push.automation = true
configuration.push.automation.requestAuthorizationAtLaunch = false

1
2
3
// Enable all automations and disable the automatic notification authorization request at launch.
configuration.push.automation = [[BRZConfigurationPushAutomation alloc] initEnablingAllAutomations:YES];
configuration.push.automation.requestAuthorizationAtLaunch = NO;

Voir Braze.Configuration.Push.Automation pour connaître toutes les options disponibles et automation pour plus d’informations sur le comportement de l’automatisation.

Vous pouvez sauter la section suivante et passer à la création de liens profonds si vous utilisez l’intégration push automatique.

Intégration manuelle par poussée

Les notifications push peuvent également être intégrées manuellement. Cette section décrit les étapes nécessaires à cette intégration.

Étape 1 : S’inscrire aux notifications push avec les APN

Incluez l’exemple de code approprié dans la méthode de délégationapplication:didFinishLaunchingWithOptions: de votre application afin que les appareils de vos utilisateurs puissent s’enregistrer auprès des APN. Assurez-vous d’appeler tout le code d’intégration push dans le thread principal de votre application.

Braze fournit également des catégories push par défaut pour la prise en charge des boutons d’action push, qui doivent être ajoutées manuellement à votre code d’enregistrement push. Reportez-vous aux boutons d’action push pour connaître les étapes d’intégration supplémentaires.

Ajoutez le code suivant à la méthode application:didFinishLaunchingWithOptions: de votre délégué d’application.

• swift
• objectif-c

1
2
3
4
5
6
7
8
9
10
11
application.registerForRemoteNotifications()
let center = UNUserNotificationCenter.current()
center.setNotificationCategories(Braze.Notifications.categories)
center.delegate = self
var options: UNAuthorizationOptions = [.alert, .sound, .badge]
if #available(iOS 12.0, *) {
  options = UNAuthorizationOptions(rawValue: options.rawValue | UNAuthorizationOptions.provisional.rawValue)
}
center.requestAuthorization(options: options) { granted, error in
  print("Notification authorization, granted: \(granted), error: \(String(describing: error))")
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[application registerForRemoteNotifications];
UNUserNotificationCenter *center = UNUserNotificationCenter.currentNotificationCenter;
[center setNotificationCategories:BRZNotifications.categories];
center.delegate = self;
UNAuthorizationOptions options = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
if (@available(iOS 12.0, *)) {
  options = options | UNAuthorizationOptionProvisional;
}
[center requestAuthorizationWithOptions:options
                      completionHandler:^(BOOL granted, NSError *_Nullable error) {
                        NSLog(@"Notification authorization, granted: %d, "
                              @"error: %@)",
                              granted, error);
}];

Étape 2 : Enregistrer des jetons avec Braze

Une fois l’enregistrement des APN terminé, transmettez le deviceToken généré à Braze pour activer les notifications push pour l’utilisateur.

• swift
• objectif-c

1
AppDelegate.braze?.notifications.register(deviceToken: deviceToken)

1
[AppDelegate.braze.notifications registerDeviceToken:deviceToken];

Étape 3 : Activer la gestion des notifications push

Ensuite, transmettez les notifications push reçues à Braze. Cette étape est nécessaire pour la journalisation de l’analyse/analytique push et la gestion des liens. Assurez-vous d’appeler tout le code d’intégration push dans le thread principal de votre application.

Traitement par défaut des notifications push

• swift
• objectif-c

1
2
3
4
5
6
7
if let braze = AppDelegate.braze, braze.notifications.handleBackgroundNotification(
  userInfo: userInfo,
  fetchCompletionHandler: completionHandler
) {
  return
}
completionHandler(.noData)

1
2
3
4
5
6
7
if let braze = AppDelegate.braze, braze.notifications.handleUserNotification(
  response: response,
  withCompletionHandler: completionHandler
) {
  return
}
completionHandler()

1
2
3
4
5
6
7
BOOL processedByBraze = AppDelegate.braze != nil && [AppDelegate.braze.notifications handleBackgroundNotificationWithUserInfo:userInfo
                                                                                                       fetchCompletionHandler:completionHandler];
if (processedByBraze) {
  return;
}

completionHandler(UIBackgroundFetchResultNoData);

1
2
3
4
5
6
7
BOOL processedByBraze = AppDelegate.braze != nil && [AppDelegate.braze.notifications handleUserNotificationWithResponse:response
                                                                                                  withCompletionHandler:completionHandler];
if (processedByBraze) {
  return;
}

completionHandler();

Gestion des notifications push au premier plan

• swift
• objectif-c

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
func userNotificationCenter(
  _ center: UNUserNotificationCenter,
  willPresent notification: UNNotification,
  withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions
) -> Void) {
  if let braze = AppDelegate.braze {
    // Forward notification payload to Braze for processing.
    braze.notifications.handleForegroundNotification(notification: notification)
  }

  // Configure application's foreground notification display options.
  if #available(iOS 14.0, *) {
    completionHandler([.list, .banner])
  } else {
    completionHandler([.alert])
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
  if (AppDelegate.braze != nil) {
    // Forward notification payload to Braze for processing.
    [AppDelegate.braze.notifications handleForegroundNotificationWithNotification:notification];
  }

  // Configure application's foreground notification display options.
  if (@available(iOS 14.0, *)) {
    completionHandler(UNNotificationPresentationOptionList | UNNotificationPresentationOptionBanner);
  } else {
    completionHandler(UNNotificationPresentationOptionAlert);
  }
}

Création de liens profonds

La création de liens profonds d’une notification push vers l’application est gérée automatiquement via notre documentation d’intégration push standard. Si vous souhaitez en savoir plus sur la création de liens profonds vers des emplacements/localisations spécifiques dans votre application, consultez nos cas d’utilisation avancés.

S’abonner aux mises à jour par notification push

Pour accéder aux charges utiles des notifications push traitées par Braze, utilisez la méthode Braze.Notifications.subscribeToUpdates(payloadTypes:_:).

Vous pouvez utiliser le paramètre payloadTypes pour indiquer si vous souhaitez vous abonner à des notifications concernant des événements push ouverts, des événements push reçus ou les deux.

• swift
• objectif-c

1
2
3
4
5
6
// This subscription is maintained through a Braze cancellable, which will observe for changes until the subscription is cancelled.
// You must keep a strong reference to the cancellable to keep the subscription active.
// The subscription is canceled either when the cancellable is deinitialized or when you call its `.cancel()` method.
let cancellable = AppDelegate.braze?.notifications.subscribeToUpdates(payloadTypes: [.open, .received]) { payload in
  print("Braze processed notification with title '\(payload.title)' and body '\(payload.body)'")
}

1
2
3
4
5
NSInteger filtersValue = BRZNotificationsPayloadTypeFilter.opened.rawValue | BRZNotificationsPayloadTypeFilter.received.rawValue;
BRZNotificationsPayloadTypeFilter *filters = [[BRZNotificationsPayloadTypeFilter alloc] initWithRawValue: filtersValue];
BRZCancellable *cancellable = [notifications subscribeToUpdatesWithPayloadTypes:filters update:^(BRZNotificationsPayload * _Nonnull payload) {
  NSLog(@"Braze processed notification with title '%@' and body '%@'", payload.title, payload.body);
}];

Tester

Si vous souhaitez tester des notifications push et in-app à l’aide de la ligne de commande, vous pouvez envoyer une seule notification par le terminal via cURL et l’API d’envoi de messages. Vous devrez remplacer les champs suivants par les valeurs correctes pour votre cas de test :

• YOUR_API_KEY - disponible dans Réglages > Clés API.
• YOUR_EXTERNAL_USER_ID - disponible sur la page Recherche d’utilisateurs. Pour plus d’informations, reportez-vous à la rubrique Attribution d’ID d’utilisateur.
• YOUR_KEY1 (facultatif)
• YOUR_VALUE1 (facultatif)

Dans l’exemple suivant, l’instance US-01 est utilisée. Si vous n’êtes pas sur cette instance, reportez-vous à notre documentation API pour savoir à quel endpoint adresser vos requêtes.

1
2
3
4
5
6
7
8
9
10
11
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {YOUR_API_KEY}" -d '{
  "external_user_ids":["YOUR_EXTERNAL_USER_ID"],
  "messages": {
    "apple_push": {
      "alert":"Test push",
      "extra": {
        "YOUR_KEY1":"YOUR_VALUE1"
      }
    }
  }
}' https://rest.iad-01.braze.com/messages/send

Amorces de notifications push

Les campagnes d’amorces de notifications push encouragent vos utilisateurs à activer les notifications push sur leur appareil pour votre appli. Ceci peut se faire sans personnalisation du SDK, grâce à notre amorce de notifications push sans code.