diff --git a/src/_data/sidenav/main.yml b/src/_data/sidenav/main.yml index 6d48c34098..39c5c5176c 100644 --- a/src/_data/sidenav/main.yml +++ b/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: diff --git a/src/engage/campaigns/mobile-push/index.md b/src/engage/campaigns/mobile-push/index.md new file mode 100644 index 0000000000..f4cec643e0 --- /dev/null +++ b/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 + + + +``` + +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: "") + .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:' + ``` + +2. Add the following service to the `application` tag of your `AndroidManifest.xml` file: + + ```xml + + + + + + + ``` + +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/). \ No newline at end of file diff --git a/src/engage/campaigns/mobile-push/push-campaigns.md b/src/engage/campaigns/mobile-push/push-campaigns.md new file mode 100644 index 0000000000..af00ecb1f6 --- /dev/null +++ b/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. diff --git a/src/engage/content/mobile-push.md b/src/engage/content/mobile-push.md new file mode 100644 index 0000000000..896e4ee6dc --- /dev/null +++ b/src/engage/content/mobile-push.md @@ -0,0 +1,72 @@ +--- +title: Mobile Push Template +plan: engage-premier +--- + +Use Twilio Engage to build mobile push templates to include throughout your marketing campaigns. + +## Mobile push template types + +You can choose between two mobile push template types: + +- **Media**, which contains media and text content +- **Text**, which contains text content + +## Build a mobile push message template + +> info "" +> To build mobile push templates in Engage, first [configure Engage for mobile](/docs/engage/campaigns/mobile-push/). + +Follow these steps to build a mobile push template: + +1. Navigate to **Engage > Content** and click **Create template**. +2. Select **Push**, then click **Configure**. +3. Enter a template name and select your template's language. +4. Select your template's content type, then click **Next**. + - For media templates, enter your message's title in the **Title** field, its body in the **Body** field, add the media URL, then add any desired [merge tags](#personalize-with-merge-tags). + - For text templates, enter your message's title in the **Title** field, its body in the **Body** field, then add any desired merge tags. +5. Select a [click behavior](#click-behaviors). +6. Click [Test](#test-your-mobile-push-template) or **Save** to save your template. + + +### Click behaviors + +When you build a mobile push template, you can choose between three click behaviors, which determine what happens when a user taps on the mobile push: + +| Behavior | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Open app | Opens an app. You can specify a URL to take the user to a specific screen with your app. If you don't enter a URL, this behavior will take the user to the app's home screen. | +| Open URL | Opens the specified URL. | +| Custom action | Takes any value as text input. Your app determines how to handle the value. For example, you could enter a custom action of `open_settings`, and then instruct your application to open the settings application when a user taps the push and the push arrives with `click behavior = open_settings`. | + +## 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. + +## Personalize with merge tags + +Personalize mobile push content in Engage using profile traits as merge tags in your messages. + +To personalize a mobile push, click **Add merge tags** in the template builder and select the profile traits to include in your message. + +Engage inserts the selected traits inside merge tags based on cursor placement in the message. This allows you to personalize each mobile push you send to recipients. You can also use [liquid templating](https://liquidjs.com/tags/if.html){:target="blank"} to create dynamic content in the template editor. + +> info "" +> To learn more about profile traits, visit Segment's [Computed Traits](/docs/unify/traits/computed-traits/) and [SQL Traits](/docs/unify/traits/sql-traits/) documentation. + +## Next steps + +Now that you've built a mobile push template, you're ready to begin [sending mobile push campaigns](/docs/engage/campaigns/mobile-push/push-campaigns/). \ No newline at end of file