feat(messaging): add apnsTokenReceived listener (#964)

* feat(messaging): add `getApnsToken` method (#602)

* fix(messaging): use uppercase hex for APNs token

* fix(messaging): reject when APNs token unavailable and document hex format

* refactor(messaging): extract APNs token error message to constant

* revert: remove getApnsToken method in favor of listener approach

* feat(messaging): add `apnsTokenReceived` listener (#602)

* style(messaging): format code

* style: format

* Revert "style: format"

This reverts commit 1e89351.

Author: robingenz

.changeset/feat-apns-token-received.md

@@ -0,0 +1,5 @@
+---
+'@capacitor-firebase/messaging': minor
+---
+
+feat: add `apnsTokenReceived` listener

packages/messaging/README.md

@@ -283,6 +283,7 @@ const removeAllListeners = async () => {
 * [`addListener('tokenReceived', ...)`](#addlistenertokenreceived-)
 * [`addListener('notificationReceived', ...)`](#addlistenernotificationreceived-)
 * [`addListener('notificationActionPerformed', ...)`](#addlistenernotificationactionperformed-)
+* [`addListener('apnsTokenReceived', ...)`](#addlistenerapnstokenreceived-)
 * [`removeAllListeners()`](#removealllisteners)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
@@ -596,6 +597,28 @@ Only available for Android and iOS.
 --------------------
 
 
+### addListener('apnsTokenReceived', ...)
+
+```typescript
+addListener(eventName: 'apnsTokenReceived', listenerFunc: ApnsTokenReceivedListener) => Promise<PluginListenerHandle>
+```
+
+Called when the APNs token is received.
+
+Only available for iOS.
+
+| Param              | Type                                                                            |
+| ------------------ | ------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'apnsTokenReceived'</code>                                                |
+| **`listenerFunc`** | <code><a href="#apnstokenreceivedlistener">ApnsTokenReceivedListener</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
 ### removeAllListeners()
 
 ```typescript
@@ -743,6 +766,13 @@ Remove all listeners for this plugin.
 | **`notification`** | <code><a href="#notification">Notification</a></code> | The notification in which the action was performed.              | 0.2.2 |
 
 
+#### ApnsTokenReceivedEvent
+
+| Prop        | Type                | Description                                               | Since |
+| ----------- | ------------------- | --------------------------------------------------------- | ----- |
+| **`token`** | <code>string</code> | The native APNs token as an uppercase hex-encoded string. | 8.2.0 |
+
+
 ### Type Aliases
 
 
@@ -777,6 +807,13 @@ Callback to receive the notification action performed event.
 <code>(event: <a href="#notificationactionperformedevent">NotificationActionPerformedEvent</a>): void</code>
 
 
+#### ApnsTokenReceivedListener
+
+Callback to receive the APNs token received event.
+
+<code>(event: <a href="#apnstokenreceivedevent">ApnsTokenReceivedEvent</a>): void</code>
+
+
 ### Enums
 
 

packages/messaging/ios/Plugin/FirebaseMessagingPlugin.swift

@@ -34,6 +34,7 @@ public class FirebaseMessagingPlugin: CAPPlugin, CAPBridgedPlugin {
     public let tokenReceivedEvent = "tokenReceived"
     public let notificationReceivedEvent = "notificationReceived"
     public let notificationActionPerformedEvent = "notificationActionPerformed"
+    public let apnsTokenReceivedEvent = "apnsTokenReceived"
     public let errorTopicMissing = "topic must be provided."
     public let errorNotificationsMissing = "notifications must be provided."
     public let errorNotificationsInvalid = "The provided notifications are invalid."
@@ -221,6 +222,10 @@ public class FirebaseMessagingPlugin: CAPPlugin, CAPBridgedPlugin {
             return
         }
         Messaging.messaging().apnsToken = deviceToken
+        let token = deviceToken.reduce("", {$0 + String(format: "%02X", $1)})
+        var result = JSObject()
+        result["token"] = token
+        notifyListeners(apnsTokenReceivedEvent, data: result, retainUntilConsumed: true)
     }
 
     @objc private func didReceiveRemoteNotification(notification: NSNotification) {

packages/messaging/src/definitions.ts

@@ -176,6 +176,17 @@ export interface FirebaseMessagingPlugin {
     eventName: 'notificationActionPerformed',
     listenerFunc: NotificationActionPerformedListener,
   ): Promise<PluginListenerHandle>;
+  /**
+   * Called when the APNs token is received.
+   *
+   * Only available for iOS.
+   *
+   * @since 8.2.0
+   */
+  addListener(
+    eventName: 'apnsTokenReceived',
+    listenerFunc: ApnsTokenReceivedListener,
+  ): Promise<PluginListenerHandle>;
   /**
    * Remove all listeners for this plugin.
    *
@@ -454,6 +465,13 @@ export type NotificationActionPerformedListener = (
   event: NotificationActionPerformedEvent,
 ) => void;
 
+/**
+ * Callback to receive the APNs token received event.
+ *
+ * @since 8.2.0
+ */
+export type ApnsTokenReceivedListener = (event: ApnsTokenReceivedEvent) => void;
+
 /**
  * @since 0.2.2
  */
@@ -464,6 +482,18 @@ export interface TokenReceivedEvent {
   token: string;
 }
 
+/**
+ * @since 8.2.0
+ */
+export interface ApnsTokenReceivedEvent {
+  /**
+   * The native APNs token as an uppercase hex-encoded string.
+   *
+   * @since 8.2.0
+   */
+  token: string;
+}
+
 /**
  * @since 0.2.2
  */