Skip to content

Commit 730f9d6

Browse files
rchinn1rchinn1
authored
Merge branch 'master' into develop
2 parents 9fb3558 + a23f99b commit 730f9d6

File tree

4 files changed

+428
-0
lines changed

4 files changed

+428
-0
lines changed

‎src/_data/sidenav/main.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -437,6 +437,8 @@ sections:
437437
title: SMS Template
438438
- path: '/engage/content/whatsapp'
439439
title: WhatsApp Template
440+
- path: '/engage/content/mobile-push'
441+
title: Mobile Push Template
440442
- section_title: Campaigns
441443
description: "Create multi-channel campaigns to get the right message to your users."
442444
section:
@@ -450,6 +452,13 @@ sections:
450452
title: Broadcasts
451453
- path: '/engage/campaigns/whatsapp-campaigns'
452454
title: WhatsApp Campaigns
455+
- section_title: Mobile Push
456+
slug: /engage/campaigns/mobile-push
457+
section:
458+
- path: /engage/campaigns/mobile-push
459+
title: Mobile Push Onboarding
460+
- path: /engage/campaigns/mobile-push/push-campaigns
461+
title: Mobile Push Campaigns
453462
- section_title: Trait Activation
454463
slug: engage/trait-activation
455464
section:

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

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
---
2+
title: Mobile Push Onboarding
3+
plan: engage-premier
4+
---
5+
6+
This page walks you through the process of setting up mobile push notifications using Segment, Twilio, and Firebase/Apple Developer.
7+
8+
> info "Prerequisites"
9+
> This guide assumes familiarity with Swift and Kotlin and is intended for a developer audience.
10+
11+
## Overview
12+
13+
You'll set up mobile push in four stages:
14+
15+
1. [Set up analytics for mobile push](#1-set-up-analytics-for-mobile-push).
16+
2. [Add the Engage SDK plugin](#2-add-the-engage-sdk-plugin).
17+
3. [Configure push credentials](#3-configure-push-credentials).
18+
4. [Configure mobile push in Engage](#4-configure-mobile-push-in-engage).
19+
20+
## 1. Set up analytics for mobile push
21+
22+
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.
23+
24+
### Add the Segment base SDK
25+
26+
This section outlines the process for adding Segment's base SDK to your app, including the Analytics Kotlin, Analytics-Swift, and React Native libraries.
27+
28+
#### Kotlin
29+
30+
> info ""
31+
> You must initialize your Analytics instance in the Application class, otherwise you may experience issues with customization and delivery confirmation.
32+
33+
Follow these steps to integrate Analytics Kotlin:
34+
35+
1. Create a source by navigating to **Connections > Sources > Add Source**.
36+
2. Search for **Kotlin (Android)**, then click **Add source**.
37+
3. Add the Analytics dependency to your `build.gradle` file.
38+
4. Initialize and configure the client according to your requirements.
39+
5. Add the following permissions to `AndroidManifest.xml`:
40+
41+
```java
42+
<uses-permission android:name="android.permission.INTERNET"/>
43+
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
44+
45+
```
46+
47+
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).
48+
49+
50+
#### Swift
51+
52+
Follow these steps to integrate Analytics-Swift for iOS & Apple:
53+
54+
1. Create a source by navigating to **Connections > Sources > Add Source**.
55+
2. Search for **Apple**, then click **Add source**.
56+
3. Add the Analytics dependency to your application using either Swift package manager or Xcode.
57+
4. Initialize and configure the Analytics-Swift client.
58+
59+
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).
60+
61+
#### React Native
62+
63+
Follow these steps to integrate the React Native library:
64+
65+
1. Create a source by navigating to **Connections > Sources > Add Source**.
66+
2. Search for **React Native**, then click **Add source**.
67+
3. Use yarn or npm to install `@segment/analytics-react-native`, `@segment/sovran-react-native`, and `react-native-get-random-values`.
68+
4. Initialize and configure the Analytics React Native client.
69+
70+
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).
71+
72+
## 2. Add the Engage SDK plugin
73+
74+
Next, you'll add the Engage SDK plugins for both iOS and Android to your application.
75+
76+
### Instructions for iOS
77+
78+
Now that you've integrated Analytics-Swift, follow the steps in this section to add the Engage Plugin for iOS.
79+
80+
#### 2a. Add the Engage SDK plugin dependency
81+
82+
You can add the Engage SDK plugin using either Xcode or `Package.swift`.
83+
84+
**Instructions for adding the plugin with Xcode**
85+
86+
1. In the Xcode `File` menu, click **Add Packages**.
87+
2. In the Swift packages search dialog, enter the following URL:
88+
89+
```
90+
https://github.com/segment-integrations/analytics-swift-engage
91+
```
92+
93+
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`.
94+
95+
**Instructions for adding the plugin with `Package.swift`**
96+
97+
1. Open the `Package.swift` file and add the following to the `dependencies` section:
98+
99+
```
100+
.package(
101+
name: "Segment",
102+
url: "https://github.com/segment-integrations/analytics-swift-engage.git",
103+
from: "1.1.2"
104+
),
105+
```
106+
107+
#### 2b. Import the plugin
108+
109+
1. Import the plugin in the file where you configure your Analytics instance:
110+
111+
```
112+
import Segment
113+
import TwilioEngage // <-- Add this line.
114+
```
115+
116+
2. After your Analytics-Swift library setup, call `analytics.add(plugin: ...)` to add an instance of the plugin to the Analytics timeline:
117+
118+
```
119+
let analytics = Analytics(configuration: Configuration(writeKey: "<YOUR WRITE KEY>")
120+
.flushAt(3)
121+
.trackApplicationLifecycleEvents(true))
122+
123+
let engage = TwilioEngage { previous, current in
124+
print("Push Status Changed /(current)")
125+
}
126+
127+
analytics.add(plugin: engage)
128+
```
129+
130+
3. To start receiving and handling mobile push notifications, add or modify the following methods in your `AppDelegate`:
131+
132+
```swift
133+
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
134+
135+
//Add the following:
136+
137+
let center = UNUserNotificationCenter.current()
138+
center.delegate = self
139+
center.requestAuthorization(options: [.sound, .alert, .badge]) { (granted, error) in
140+
guard granted else {
141+
Analytics.main.declinedRemoteNotifications()
142+
Tab1ViewController.addPush(s: "User Declined Notifications")
143+
return
144+
}
145+
DispatchQueue.main.async {
146+
UIApplication.shared.registerForRemoteNotifications()
147+
}
148+
}
149+
150+
// The following conditional statement is necessary to handle remote notifications in older versions of iOS.
151+
if let notification = launchOptions?[UIApplication.LaunchOptionsKey.remoteNotification] as? [String: Codable] {
152+
Tab1ViewController.addPush(s: "App Launched via Notification \(notification)")
153+
Analytics.main.receivedRemoteNotification(userInfo: notification)
154+
}
155+
156+
...
157+
158+
return true
159+
}
160+
161+
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
162+
// Segment event to register for remote notifications
163+
Analytics.main.registeredForRemoteNotifications(deviceToken: deviceToken)
164+
}
165+
166+
func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
167+
// Segment event for failure to register for remote notifications
168+
Analytics.main.failedToRegisterForRemoteNotification(error: error)
169+
}
170+
171+
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) async -> UIBackgroundFetchResult {
172+
// Segment event for receiving a remote notification
173+
Analytics.main.receivedRemoteNotification(userInfo: userInfo)
174+
175+
// TODO: Customize notification handling based on the received userInfo.
176+
// Implement actions or UI updates based on the notification content.
177+
178+
return .noData
179+
}
180+
181+
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse) async {
182+
let userInfo = response.notification.request.content.userInfo
183+
//Segment event for receiving a remote notification
184+
Analytics.main.receivedRemoteNotification(userInfo: userInfo)
185+
186+
// TODO: Customize notification response handling based on the received userInfo.
187+
// Implement actions based on the user's response to the notification.
188+
// Example: Navigate to a specific screen or perform an action based on the notification.
189+
190+
}
191+
```
192+
193+
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.
194+
195+
### Instructions for Android
196+
197+
Now that you've integrated Analytics for Kotlin, follow these steps to add the Engage Plugin for Android:
198+
199+
1. Add the following to your Gradle dependencies:
200+
201+
```groovy
202+
implementation 'com.segment.analytics.kotlin.destinations:engage:<LATEST_VERSION>'
203+
```
204+
205+
2. Add the following service to the `application` tag of your `AndroidManifest.xml` file:
206+
207+
```xml
208+
<service
209+
android:name="com.segment.analytics.kotlin.destinations.engage.EngageFirebaseMessagingService"
210+
android:exported="true">
211+
<intent-filter>
212+
<action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
213+
<action android:name="com.google.firebase.MESSAGING_EVENT" />
214+
</intent-filter>
215+
</service>
216+
```
217+
218+
3. Add this plugin to your Analytics instance:
219+
220+
```kotlin
221+
analytics.add(TwilioEngage(applicationContext))
222+
```
223+
224+
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.
225+
226+
## 3. Configure push credentials
227+
228+
In this step, you'll configure your iOS and Android push credentials for use with Twilio Notify and Twilio Notifications.
229+
230+
### Configure iOS push notifications
231+
232+
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"}.
233+
234+
### Configure Android push notifications
235+
236+
Follow the steps in Twilio's [Configuring Android Push Notifications](https://www.twilio.com/docs/notify/configure-android-push-notifications){:target="_blank"}.
237+
238+
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:
239+
240+
1. In the Firebase console, click the **Cloud Messaging** tab.
241+
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.
242+
3. In the new Cloud Messaging window, select **Enable**.
243+
4. Return to the Firebase Cloud Messaging tab and refresh the page.
244+
5. Cloud Messaging API (Legacy) is now enabled. Copy the server key; you'll need it later.
245+
246+
With your server key copied, finish steps 5 and 6 in the Twilio documentation.
247+
248+
## 4. Configure mobile push in Engage
249+
250+
Follow these steps to set up mobile push in Twilio Engage.
251+
252+
### 4a. Set up Twilio credentials
253+
254+
> success ""
255+
> 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.
256+
257+
1. In your Twilio console, select the **Account** dropdown menu, then **API keys & tokens**.
258+
2. On the Auth tokens & API keys page, click **Create API key**.
259+
3. Enter a name for the API key in the **Friendly name** field.
260+
4. Set the region to **United States (US1) - Default** and key type to **Main**.
261+
5. Click **Create API Key**.
262+
6. Copy and save both the **SID** and **Secret** field contents.
263+
7. Return to the API keys & tokens page. In the **Live credentials** section, copy the Account SID credentials.
264+
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.
265+
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.
266+
12. Click **Verify**, then select the messaging services you want to use in your space.
267+
13. Click **Save Twilio Account.**
268+
269+
### 4b. Create a new push service
270+
271+
Complete mobile push onboarding by creating a new push service:
272+
273+
2. In your Segment workspace, navigate to **Engage > Engage settings**.
274+
3. Click the pencil icon next to **Messaging services**, then click **Create new push service**.
275+
- If you don't see the pencil icon, select **Create new push service**.
276+
4. Name the push service, select or create APN and FCM credentials, then click **Create Push Service**.
277+
5. Your new messaging service appears in the **Add messaging services** dropdown. Select it, then click **Save**.
278+
279+
## 5. Build a mobile push template
280+
281+
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

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Mobile Push Campaigns
3+
plan: engage-premier
4+
---
5+
6+
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.
7+
8+
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.
9+
10+
## How Engage campaigns work
11+
12+
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.
13+
14+
You’ll build and then send your campaign in three stages:
15+
16+
1. Create a journey.
17+
2. Add a journey condition.
18+
3. Create, test, and publish your mobile push campaign.
19+
20+
### Create a journey
21+
22+
Because Engage campaigns exist within Journeys, begin by creating a journey:
23+
24+
1. In Engage, select **Journeys**, then click **New Journey**.
25+
2. Name your journey and select its entry settings.
26+
3. Click **Build Journey** to create the journey.
27+
28+
### Add a Journey condition
29+
30+
With your Journey created, you’ll now create a [condition](/docs/engage/journeys/step-types/) that will trigger your campaign:
31+
32+
1. Within the Journey builder, click **+ Add Entry Condition**.
33+
2. In the Add Entry Condition pane, give the step a name.
34+
3. Click **+ Add Condition**, select your desired condition, then click **Save**.
35+
36+
With your entry condition added, you’re now ready to create your mobile push campaign.
37+
38+
### Create, test, and publish your mobile push campaign
39+
40+
Follow these steps to create a mobile push campaign:
41+
42+
1. Within the Journey builder, click the **+** node below your new condition.
43+
2. From the **Add step** window, click **Send a Push**.
44+
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/).
45+
4. Review your template's content and click behavior, then click [Test](#test-your-mobile-push-template) or **Continue**.
46+
5. In the **Send a Push** modal, give the step a name, choose a messaging service, add any conversion goals, then click **Save**.
47+
6. In the Journey builder, click **Publish**.
48+
49+
Your mobile push campaign is now live. Users who trigger the mobile push step’s parent Journey condition will receive your campaign.
50+
51+
## Test your mobile push template
52+
53+
> info "Push tokens"
54+
> 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.
55+
56+
Follow these steps to test your mobile push:
57+
58+
1. Choose a template to test:
59+
- For new templates, select **Test** once you've finished building a template.
60+
- For existing templates, navigate to **Engage > Content > Push**, select the template you want to test, then click **Test**.
61+
- Mobile push templates have a content size limit of 4KB.
62+
2. Choose a messaging service and add a recipient.
63+
- You can add recipients using an email address or user ID.
64+
3. Click **Send test push**.
65+
66+
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.

0 commit comments

Comments
 (0)