Mobile Push GA [DOC-714]

src/_data/sidenav/main.yml

@@ -435,6 +435,8 @@ sections:
       title: SMS Template
     - path: '/engage/content/whatsapp'
       title: WhatsApp Template
+    - path: '/engage/content/mobile-push'
+      title: Mobile Push Template
   - section_title: Campaigns
     description: "Create multi-channel campaigns to get the right message to your users."
     section:
@@ -448,6 +450,13 @@ sections:
       title: Broadcasts
     - path: '/engage/campaigns/whatsapp-campaigns'
       title: WhatsApp Campaigns
+    - section_title: Mobile Push
+      slug: /engage/campaigns/mobile-push
+      section:
+      - path: /engage/campaigns/mobile-push
+        title: Mobile Push Onboarding
+      - path: /engage/campaigns/mobile-push/push-campaigns
+        title: Mobile Push Campaigns
   - section_title: Trait Activation
     slug: engage/trait-activation
     section:

src/engage/campaigns/mobile-push/index.md

@@ -0,0 +1,281 @@
+---
+title: Mobile Push Onboarding
+plan: engage-premier
+---
+
+This page walks you through the process of setting up mobile push notifications using Segment, Twilio, and Firebase/Apple Developer.
+
+> info "Prerequisites"
+> This guide assumes familiarity with Swift and Kotlin and is intended for a developer audience. 
+
+## Overview
+
+You'll set up mobile push in four stages:
+
+1. [Set up analytics for mobile push](#1-set-up-analytics-for-mobile-push).
+2. [Add the Engage SDK plugin](#2-add-the-engage-sdk-plugin).
+3. [Configure push credentials](#3-configure-push-credentials).
+4. [Configure mobile push in Engage](#4-configure-mobile-push-in-engage).
+
+## 1. Set up analytics for mobile push
+
+Before you can send mobile pushes, you'll need to set up analytics. In this step, you'll integrate Segment's mobile SDK into your app.
+
+### Add the Segment base SDK
+
+This section outlines the process for adding Segment's base SDK to your app, including the Analytics Kotlin, Analytics-Swift, and React Native libraries.
+
+#### Kotlin
+
+> info ""
+> You must initialize your Analytics instance in the Application class, otherwise you may experience issues with customization and delivery confirmation.
+
+Follow these steps to integrate Analytics Kotlin:
+
+1. Create a source by navigating to **Connections > Sources > Add Source**.
+2. Search for **Kotlin (Android)**, then click **Add source**.
+3. Add the Analytics dependency to your `build.gradle` file.
+4. Initialize and configure the client according to your requirements.
+5. Add the following permissions to `AndroidManifest.xml`:
+
+```java
+ <uses-permission android:name="android.permission.INTERNET"/>
+ <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
+
+```
+
+For detailed instructions on integrating Analytics Kotlin, follow the steps in the [Analytics Kotlin getting started section](/docs/connections/sources/catalog/libraries/mobile/kotlin-android#getting-started).
+
+
+#### Swift
+
+Follow these steps to integrate Analytics-Swift for iOS & Apple:
+
+1. Create a source by navigating to **Connections > Sources > Add Source**.
+2. Search for **Apple**, then click **Add source**.
+3. Add the Analytics dependency to your application using either Swift package manager or Xcode.
+4. Initialize and configure the Analytics-Swift client.
+
+For detailed instructions on integrating Analytics-Swift, follow the steps in the [Analytics-Swift getting started section](/docs/connections/sources/catalog/libraries/mobile/apple#getting-started).
+
+#### React Native
+
+Follow these steps to integrate the React Native library:
+
+1. Create a source by navigating to **Connections > Sources > Add Source**.
+2. Search for **React Native**, then click **Add source**.
+3. Use yarn or npm to install `@segment/analytics-react-native`, `@segment/sovran-react-native`, and `react-native-get-random-values`.
+4. Initialize and configure the Analytics React Native client.
+
+For detailed instructions on integrating Analytics for React Native, follow the steps in the [Analytics for React Native getting started section](/docs/connections/sources/catalog/libraries/mobile/react-native#getting-started). 
+
+## 2. Add the Engage SDK plugin
+
+Next, you'll add the Engage SDK plugins for both iOS and Android to your application.   
+
+### Instructions for iOS
+
+Now that you've integrated Analytics-Swift, follow the steps in this section to add the Engage Plugin for iOS.
+
+#### 2a. Add the Engage SDK plugin dependency
+
+You can add the Engage SDK plugin using either Xcode or `Package.swift`.
+
+**Instructions for adding the plugin with Xcode**
+
+1. In the Xcode `File` menu, click **Add Packages**. 
+2. In the Swift packages search dialog, enter the following URL:
+
+    ```
+    https://github.com/segment-integrations/analytics-swift-engage
+    ```
+
+3. You'll then have the option to pin to a version or a specific branch, as well as to the project in your workspace. Once you've made your selections, click `Add Package`.
+
+**Instructions for adding the plugin with `Package.swift`**
+
+1. Open the `Package.swift` file and add the following to the `dependencies` section:
+
+```
+.package(
+            name: "Segment",
+            url: "https://github.com/segment-integrations/analytics-swift-engage.git",
+            from: "1.1.2"
+        ),
+```
+
+#### 2b. Import the plugin 
+
+1. Import the plugin in the file where you configure your Analytics instance:
+
+    ```
+    import Segment
+    import TwilioEngage // <-- Add this line.
+    ```
+
+2. After your Analytics-Swift library setup, call `analytics.add(plugin: ...)` to add an instance of the plugin to the Analytics timeline:
+
+    ```
+    let analytics = Analytics(configuration: Configuration(writeKey: "<YOUR WRITE KEY>")
+                        .flushAt(3)
+                        .trackApplicationLifecycleEvents(true))
+
+    let engage = TwilioEngage { previous, current in
+        print("Push Status Changed /(current)")
+    }
+
+    analytics.add(plugin: engage)
+    ```
+
+3. To start receiving and handling mobile push notifications, add or modify the following methods in your `AppDelegate`:
+
+```swift
+   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+
+    //Add the following:
+
+        let center  = UNUserNotificationCenter.current()
+        center.delegate = self
+        center.requestAuthorization(options: [.sound, .alert, .badge]) { (granted, error) in
+            guard granted else {
+                Analytics.main.declinedRemoteNotifications()
+                Tab1ViewController.addPush(s: "User Declined Notifications")
+                return
+            }
+            DispatchQueue.main.async {
+                UIApplication.shared.registerForRemoteNotifications()
+            }
+        }
+
+        // The following conditional statement is necessary to handle remote notifications in older versions of iOS.
+        if let notification = launchOptions?[UIApplication.LaunchOptionsKey.remoteNotification] as? [String: Codable] {
+            Tab1ViewController.addPush(s: "App Launched via Notification \(notification)")
+            Analytics.main.receivedRemoteNotification(userInfo: notification)
+        }
+
+        ...
+
+        return true
+}
+
+func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+    // Segment event to register for remote notifications
+    Analytics.main.registeredForRemoteNotifications(deviceToken: deviceToken)
+}
+
+func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
+    // Segment event for failure to register for remote notifications
+    Analytics.main.failedToRegisterForRemoteNotification(error: error)
+}
+
+func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) async -> UIBackgroundFetchResult {
+    // Segment event for receiving a remote notification
+    Analytics.main.receivedRemoteNotification(userInfo: userInfo)
+
+    // TODO: Customize notification handling based on the received userInfo.
+    // Implement actions or UI updates based on the notification content.
+
+    return .noData
+}
+
+func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse) async {
+    let userInfo = response.notification.request.content.userInfo
+    //Segment event for receiving a remote notification
+    Analytics.main.receivedRemoteNotification(userInfo: userInfo)
+
+    // TODO: Customize notification response handling based on the received userInfo.
+    // Implement actions based on the user's response to the notification.
+    // Example: Navigate to a specific screen or perform an action based on the notification.
+
+}
+```
+
+The previous steps are required. For configuration options, including subscription statuses and media handling, visit the [getting started section](https://github.com/segment-integrations/analytics-swift-engage#getting-started){:target="_blank"} of Segment's Twilio Engage Plugin documentation on GitHub.
+
+### Instructions for Android
+
+Now that you've integrated Analytics for Kotlin, follow these steps to add the Engage Plugin for Android:
+
+1. Add the following to your Gradle dependencies:
+
+    ```groovy
+        implementation 'com.segment.analytics.kotlin.destinations:engage:<LATEST_VERSION>'
+    ```
+
+2. Add the following service to the `application` tag of your `AndroidManifest.xml` file:
+
+    ```xml
+        <service
+            android:name="com.segment.analytics.kotlin.destinations.engage.EngageFirebaseMessagingService"
+            android:exported="true">
+            <intent-filter>
+            <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
+            <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+    ```
+
+3. Add this plugin to your Analytics instance:
+
+    ```kotlin
+        analytics.add(TwilioEngage(applicationContext))
+    ```
+
+The previous steps are required. For configuration options, including subscription statuses and customized actions, visit the [getting started section](https://github.com/segment-integrations/analytics-kotlin-engage#getting-started){:target="_blank"} of Segment's Twilio Engage Destination documentation on GitHub.
+
+## 3. Configure push credentials
+
+In this step, you'll configure your iOS and Android push credentials for use with Twilio Notify and Twilio Notifications.  
+
+### Configure iOS push notifications
+
+Follow the steps in Twilio's [How to Configure iOS Push Notifications documentation](https://www.twilio.com/docs/notify/configure-ios-push-notifications){:target="_blank"}.
+
+### Configure Android push notifications 
+
+Follow the steps in Twilio's [Configuring Android Push Notifications](https://www.twilio.com/docs/notify/configure-android-push-notifications){:target="_blank"}.
+
+During Step 5, [Upload your API Key to Twilio](https://www.twilio.com/docs/notify/configure-android-push-notifications#step-5-upload-your-api-key-to-twilio){:target="_blank"}, follow these steps:
+
+1. In the Firebase console, click the **Cloud Messaging** tab.
+2. Select the three dots menu next to **Cloud Messaging API (Legacy) Disabled**, then select **Manage API in Google Cloud Console**. A new window opens.
+3. In the new Cloud Messaging window, select **Enable**.
+4. Return to the Firebase Cloud Messaging tab and refresh the page.
+5. Cloud Messaging API (Legacy) is now enabled. Copy the server key; you'll need it later.
+
+With your server key copied, finish steps 5 and 6 in the Twilio documentation.
+
+## 4. Configure mobile push in Engage
+
+Follow these steps to set up mobile push in Twilio Engage.
+
+### 4a. Set up Twilio credentials
+
+> success ""
+> Follow the steps in 4a only if you're new to Twilio Engage Premier. If you've already [configured messaging services](/docs/engage/onboarding/#generate-an-api-key-and-select-your-messaging-services) as part of Twilio Engage Premier onboarding, you can skip to 4b.
+
+1. In your Twilio console, select the **Account** dropdown menu, then **API keys & tokens**.
+2. On the Auth tokens & API keys page, click **Create API key**.
+3. Enter a name for the API key in the **Friendly name** field.
+4. Set the region to **United States (US1) - Default** and key type to **Main**.
+5. Click **Create API Key**.
+6. Copy and save both the **SID** and **Secret** field contents.
+7. Return to the API keys & tokens page. In the **Live credentials** section, copy the Account SID credentials.
+8. Return to your Segment workspace and navigate to **Engage > Engage settings > Channels**.  Under **SMS Service with Twilio**, click the **Get Started** button. The **Set up and validate your Twilio account** page appears.
+11. Under **Enter your Twilio API Key information**, paste the Account SID, API Key SID, and API Key Secret you copied above into their corresponding fields.
+12. Click **Verify**, then select the messaging services you want to use in your space.
+13. Click **Save Twilio Account.**
+
+### 4b. Create a new push service
+
+Complete mobile push onboarding by creating a new push service:
+
+2. In your Segment workspace, navigate to **Engage > Engage settings**.
+3. Click the pencil icon next to **Messaging services**, then click **Create new push service**.
+    - If you don't see the pencil icon, select **Create new push service**.
+4. Name the push service, select or create APN and FCM credentials, then click **Create Push Service**.
+5. Your new messaging service appears in the **Add messaging services** dropdown. Select it, then click **Save**.
+
+## 5. Build a mobile push template
+
+Now that you've completed mobile push setup, you're ready to [build a mobile push template](/docs/engage/content/mobile-push/).

src/engage/campaigns/mobile-push/push-campaigns.md

@@ -0,0 +1,66 @@
+---
+title: Mobile Push Campaigns
+plan: engage-premier
+---
+
+With Twilio Engage, you can send campaigns to users who have opted in to receive your marketing materials. On this page, you’ll learn how to create and send a mobile push campaign.
+
+Some knowledge of the Journeys product will benefit you as you read through this guide. If you’re new to Journeys, the [Journeys documentation](/docs/personas/journeys/) will bring you up to speed.
+
+## How Engage campaigns work
+
+Twilio Engage uses Journeys to send campaigns.  With Journeys, you add conditions and steps that trigger actions like sending an email, an SMS, or a mobile push.
+
+You’ll build and then send your campaign in three stages:
+
+1. Create a journey.
+2. Add a journey condition.
+3. Create, test, and publish your mobile push campaign.
+
+### Create a journey
+
+Because Engage campaigns exist within Journeys, begin by creating a journey:
+
+1. In Engage, select **Journeys**, then click **New Journey**.
+2. Name your journey and select its entry settings.
+3. Click **Build Journey** to create the journey.
+
+### Add a Journey condition
+
+With your Journey created, you’ll now create a [condition](/docs/engage/journeys/step-types/) that will trigger your campaign:
+
+1. Within the Journey builder, click **+ Add Entry Condition**.
+2. In the Add Entry Condition pane, give the step a name.
+3. Click **+ Add Condition**, select your desired condition, then click **Save**.
+
+With your entry condition added, you’re now ready to create your mobile push campaign. 
+
+### Create, test, and publish your mobile push campaign
+
+Follow these steps to create a mobile push campaign:
+
+1. Within the Journey builder, click the **+** node below your new condition.
+2. From the **Add step** window, click **Send a Push**.
+3. In the **Send a Push** window, select the mobile push template you want to use, or click **Create new template** to [build a new template](/docs/engage/content/mobile-push/).
+4. Review your template's content and click behavior, then click [Test](#test-your-mobile-push-template) or **Continue**.
+5. In the **Send a Push** modal, give the step a name, choose a messaging service, add any conversion goals, then click **Save**.
+6. In the Journey builder, click **Publish**.
+
+Your mobile push campaign is now live. Users who trigger the mobile push step’s parent Journey condition will receive your campaign.
+
+## Test your mobile push template
+
+> info "Push tokens"
+> Push tokens are unique identifiers Segment associates with each profile. For mobile push, you'll need to configure identity resolution settings for the push tokens `ios.push_token` and `android.push_token`. Using the Profile explorer, you can find a profile's push tokens by opening a profile and then selecting the Identities tab. You can only send mobile pushes to profiles with push tokens enabled.
+
+Follow these steps to test your mobile push:
+
+1. Choose a template to test:
+    - For new templates, select **Test** once you've finished building a template. 
+    - For existing templates, navigate to **Engage > Content > Push**, select the template you want to test, then click **Test**.
+    - Mobile push templates have a content size limit of 4KB.
+2. Choose a messaging service and add a recipient.
+    - You can add recipients using an email address or user ID. 
+3. Click **Send test push**.
+
+Segment verifies that the profile you're sending a test to has a push token, then sends the test. If the test mobile push doesn't work as expected, confirm that the profile you're sending to has a push token.