Supported actions

Use Swrve’s integration with Oracle Responsys to share data between both systems and trigger actions or events in Swrve directly from a Responsys Program.

From a Responsys Program, trigger the following Swrve actions:

• Trigger In-app Message and Conversation campaigns that use your Responsys contacts list to generate the audience.
• Send rich push notifications with custom properties and deeplinks.
• Send events from Responsys to Swrve.
• Update user properties of mobile users in Swrve.

From your Swrve-powered app, you can instantly:

• Initiate a Responsys Program for a user based on their real-time actions in the app.
• Update Responsys customer profile information (Profile Extension Table) with data coming from the app.

Prerequisites

• To use Responsys with your Swrve-powered app, contact your CSM at support@swrve.com. You must have AppCloud enabled in Responsys and provide your Oracle Tenant ID, then your CSM will give you a link to install Swrve in Responsys. They will also configure and activate the Responsys integration in Swrve and enable external audiences for your Swrve campaigns. If AppCloud is not enabled, contact your Oracle account manager.
• If you’re using an external user ID to track users as part of Swrve’s User Identity feature, you need to generate an Identity secret key on the Integration Settings screen of your Swrve dashboard. For more information about managing your API keys, see Integrate your app.

Setup

To activate your Swrve-Responsys integration, you need to link your Swrve account to Responsys and provide certain Responsys credentials in Swrve.

Link your Swrve dashboard to Responsys

After you install Swrve, you need to link your Swrve dashboard to Responsys. Select any Swrve activity from the custom Apps list, and then on the configuration screen select the Link Account step to enter the credentials for your Swrve dashboard.

Once you’ve linked your account, you’ll be automatically directed to the Configure Activity screen. If you need to change your credentials, select Link Account and re-enter them. If two-factor authorization (2FA) is enabled for your Swrve account, it is not required for linking to the Responsys app.

Responsys configuration

For your CSM to configure the Reponsys integration and create the required rules in Swrve, you need to provide the following credentials:

• FTP location, file path, user name, and password – Required for bulk data upload of Swrve data into Responsys.
• Responsys user and password – Required for real-time updates from Swrve to Responsys and Swrve event-triggered Programs.
• Login URL – The login URL associated with your Responsys dashboard. This depends on the pod in which your account lives in Responsys.

Create a Program with Swrve apps

After you install the Swrve app for Responsys, the supported Swrve actions are available to use in the Program Designer canvas, as custom Apps. There are five actions available:

• Push Notification
• Conversations
• In-App Message
• Track Event
• Update User Properties

When using Swrve apps in your Responsys Program, you must include the following elements:

• Entry point – The event or interaction that triggers the program.
• Swrve app – The action you want to include in your program.
• End event

This article only covers setting up a basic program using Swrve apps. Depending on the Swrve action or if you want to include custom attributes, you might need to include other elements, such as Get or Set Data. For information about custom attributes, see below. For more details about creating programs, see the Oracle Responsys user documentation.

Add your entry point

Select one of the following entry points to trigger your program:

Scheduled filter or view – Queries a selected list or refreshes a predefined SQL view to pull in users based on the filter criteria you select, at the frequency you chose to specify.

Note: If you’re using the refresh SQL view as your program entry point, to use any data from the Profile Extension Table (PETs) in other program elements, you must include a Get Data activity in combination with the Data Switch to update the entry tracking variables with the data from the PETs.

Custom event – Triggers the program based on an event you define, either in Responsys or in Swrve using a custom rule.

Connect event – Triggers the program upon completion of a Connect import job, such as the Upload CSV action.

Add a Swrve app

Move the Apps icon to the canvas. Double-click to select the required action and then select Configure app.

For details about how to configure each action, see the relevant section below.

Swrve Push Notification

To configure a Swrve push notification, complete the following sections as required:

Swrve Campaign

• App Name – Displays a list of your Swrve apps that are linked with your Responsys account and that have active push notification campaigns (including sandbox and production apps). Select the app you want to use for the campaign.
• Push Campaign – Push notifications in Responsys use the Swrve Push API to take advantage of all of Swrve’s built-in tracking and analytics. We recommend creating a Push API campaign for each individual push you want to include in your Programs. Any push API campaigns you create in Swrve display in this list. For more information, see Push API campaigns.
• Swrve User ID – The ID Swrve uses to uniquely identify an app user.
• External User ID – If you’re using Swrve’s User Identity feature to track your users across multiple devices, platforms and channels, this is the app-specific ID you use to identify your users. Note: You must include either the Swrve User ID or an external user ID. If you include both, the external user ID is used.

Notification Content

If the selected Swrve Push API campaign contains default content, any content or rich media you add here overwrites those defaults, if specified.

• Body Text – The push notification content. This can be text that you enter directly or that is completely extracted from the Responsys contacts list or the program’s tracking variables, or a mixture of the two. To insert data from your contacts list, select the property name from the Insert Property list.
• Title – (Requires Swrve SDK 4.11+) The notification title. To include a custom property in the title, select Insert Property and then select the desired property from the available list.
• Subtitle – (Requires Swrve SDK 4.11+) For iOS10+ devices, text that is displayed as the subtitle in push notifications. For Android devices, text that is displayed after the title. To include a custom property in the subtitle, select Insert Property and then select the desired property from the available list.
• Alert Sound – To set a sound for your push notification, select the Alert Sound list and select the desired sound. For information about configuring custom sounds so that they are available in the Alert Sound list, see Intro to push notifications.
• iOS Category – If your push notification is targeted at Apple users, the iOS Category field enables you to make the notification appear as an interactive push notification on devices running iOS 8 or later. Select a custom action category (for example, Yes/No, Ignore/Respond) from the list. For information about configuring custom action categories for this list, see Intro to push notifications.
• Engagement Action Deeplink/URL – (Requires SDK version 4.3+) If you want to direct the user to a particular custom location when they engage with the notification, enter the deeplink or URL address.
• Advanced – Custom Payload – If you want instructional parameters to be sent to your app when you send the push notification, define custom key/value groups or pairs. For example, you might want to direct the user straight to the store (instead of the default start screen) when they open your app from the push notification. Alternatively, you might want tracking parameters to be passed from the push notification for use by your internal or external tracking systems. To add custom key/value pairs:
  1. Select Advanced – Custom Payload.
  2. In the Custom key/value pairs section, select Add key with sub pairs or Add key/value pair, as required.
  3. Enter a key/value pair in the Key and Value fields. For example, go_to/store, trial/30days or discount/10percent. The Payload Preview displays the actual code sent with your push notification.

  The Add key with sub pairs option enables you to nest multiple key/values under the group name in the JSON payload. Consult with your development team about the appropriate key/value pairs to use to trigger the outcome you require.

• Advanced – Rich Media – Use the options in this section to include rich media in your push notification content that is displayed on supported devices. For more information on Swrve rich push notifications, see About rich push notifications. To include rich media options, complete the following fields:
  • Media Type – The type of media you want to include in your notification content. The available options are:
    • Image – Displays the URL as an image in the locked, banner, or extended view of the push notification.
    • Audio – (iOS only) Include an audio file in your notification that a user can play directly in the extended view of the push notification.
    • Video – Links to a hosted video and provides options for watching the video in a related player (for example, YouTube, Vimeo) from the extended view of a push notification.
    • GIF – (iOS only) Displays a GIF in the extended view of the push notification.
  • Media URL – The URL of the file you want to use for your rich media content. The URL must be a valid and HTTPS URL and include a file extension. If required, you can customize the media that’s include in the notification (for example, reference a customer’s profile picture or the destination of a flight they searched for). To include a custom property in the URL, select Insert Property and then select the desired property from the available list.
  • Video Thumbnail URL –  For notifications that include a video, the URL of the thumbnail image that will be displayed on the notification in locked or banner view. To include a custom property in the URL, select Insert Property and then select the desired property from the available list.
  • Buttons – Lets you include up to three buttons to give your users custom options for interacting with the notification in extended view. Select the Add Button link and complete the following for each button:
    • Button Text – The text for the button label.
    • Action Type – The button action. The options are Open App, URL / Deeplink (directs the user to a custom location) or Dismiss.
    • URL / Deeplink – If you select URL / Deeplink, enter the deeplink or URL address for the button action.

After you’ve selected the Swrve Campaign details and added your Notification Content, to return to the Program, select Submit.

Swrve Conversations and In-App Messages

To make a Conversation, in-app message, or embedded campaign available in your Program, you must first create the campaign in Swrve. We recommend following a standard naming convention for your campaigns so they’re easy to find in the campaign list. For more information on the main steps involved, see one of the following:

• Conversations
• In-app messages
• Embedded campaigns

To make the campaign available in Responsys, on the Define Target Audience step of the campaign workflow, select External Audience, and then select Marketing Cloud.

If you’re including an in-app message or Conversation in your Program, you must add two separate actions—one that adds the user to the audience for the associated Swrve campaign and one that removes them.

To configure the in-app message or Conversation action, complete the following fields:

• App Name – Displays a list of your Swrve apps, including sandbox and production versions. Select the app you want to use for the campaign.
• Conversations or In-App Messages Campaign – Select the campaign you created in Swrve. If you don’t see your campaign in this list, ensure the Swrve campaign is set to active and that you selected Marketing Cloud as the external audience source when creating the campaign.
• Swrve User ID – The ID Swrve uses to uniquely identify an app user.
• External User ID – If you’re using Swrve’s User Identity feature to track your users across multiple devices, platforms and channels, this is the app-specific ID you use to identify your users. Note: You must include either the Swrve User ID or an external user ID. If you include both, the external user ID is used.
• Action – Select the relevant action to add or remove the user from the campaign audience.

Real-time data transfer from Responsys to Swrve

In many cases you’ll want to send information from Responsys to Swrve. This information is per user and is transferred instantly as users hit the corresponding activity in a Program.

There are two options for sending information to Swrve:

• Track Event – Send events you want to count and track over time.
• Update User Properties – Send facts about a user that hold a set value at any given moment in time.

The following sections explain how to configure these actions.

Track Event

The Swrve app enables Responsys to send custom events to Swrve. You can then use those events in Swrve to trigger other mobile campaigns such as in-app messages or other Swrve actions when the custom events are received.

To send a Swrve event as part of your Program, select the Track Event action from the Apps list.

To configure the Track Event action, complete the following fields:

• App Name – Displays a list of your Swrve apps, including sandbox and production versions. Select the app you want to use for the campaign.
• Swrve User ID – The ID Swrve uses to uniquely identify an app user.
• External User ID – If you’re using Swrve’s User Identity feature to track your users across multiple devices, platforms and channels, this is the app-specific ID you use to identify your users. Note: You must include either the Swrve User ID or an external user ID. If you include both, the external user ID is used.
• Event Name – The name of the action or behavior Swrve records for this user. Event names must be unique, alphanumeric, contain only special characters underscore (_) and periods (.) and no spaces. Swrve counts the number of times it see this information for each user and notes the time the event arrives.
• Event Content – When sending events, at times you may want to include additional information to help target behavior. That extra information is often described with a label (or key) and a value. To add a key-value pair, select Add and enter the key and value. The values of the key-value pair can be dynamically inserted from any Responsys contact attributes or data extensions.
  

Update User Properties

Use the Update User Properties action to send data you have in Responsys about non-mobile user activities to Swrve. After the Swrve user profile is updated with this information, Swrve can immediately change how it engages with the user based on this new context.

To configure the Update User action, complete the following fields:

• App Name – Displays a list of your Swrve apps, including sandbox and production versions. Select the app you want to use for the campaign.
• Swrve User ID – The ID Swrve uses to uniquely identify an app user.
• External User ID – If you’re using Swrve’s User Identity feature to track your users across multiple devices, platforms and channels, this is the app-specific ID you’re using to identify your users. Note: You must include either the Swrve User ID or an external user ID. If you include both, the external user ID is used.
• User Properties – User properties are described with a label (or key) and a value. You must include at least one. The above example illustrates how to update the user’s profile to show they now qualify for Free_Shipping and the tier of rewards they are at. First, select Add, enter a Key called Free_Shipping and set the value to TRUE. The information about tier is stored in this instance of Responsys in a field called Rewards_tier. To update the rewards tier, add a new key-value pair called Tier and use the Insert Property list to find the corresponding value in your contacts list or other data source.

To check the existing custom properties for your app, download the Custom User Properties CSV file from the User DB Downloads screen, or in the audience builder, on the Property tab, check the list of available properties in the filter list. For more information, see Intro to user databases or Segment and audience filters.

Using custom attributes

If you’re using a Profile Extension Table (PETs) or custom event from Swrve as the entry point to your program and sending data with it, to use the values as custom attributes in your program elements, you must manually add them as entry tracking variables.

To add entry tracking variables:

Step 1: On the Program canvas, select Settings.

Step 2: In the Settings box, select Tracking and variables, and then select + Add to enter the name and type of each custom attribute you want to make available.

Step 3: Select OK. After you add the entry tracking data, the values are displayed in the Insert Property list of the Swrve activity.

Use cases

• Track your users non-mobile behavior in Responsys and then trigger push notifications based on a user’s non-mobile actions/activities or an external real-time event. For example, send a push notification about an upcoming event of special interest to a specific user.
• Use non-mobile behavioral data to target and run engagement campaigns in Swrve. For example, use web purchase data received from Responsys to segment users for an in-app messaging campaign in Swrve.
• Synchronize Swrve and Responsys user records so you can run coherent mobile and non-mobile campaigns from Swrve and Responsys respectively.