Swrve / Marketo Integration...Swrve / Marketo webhooks A one-time setup process is required to...

Swrve / Marketo Integration v1.2 - February 19, 2015

© Swrve New Media Inc, 2015 1

Introduction Marketing is always changing. Currently, there’s a shift in the way we talk to customers and potential customers. Specifically, where we used to launch ‘campaigns’, which required sending hundreds, thousands (millions?) of messages to our audience, we now aim to deliver relevant, timely interactions that feel more like conversations and less like one-way ‘megaphone marketing’. But that’s not the only thing that’s changing. 2015 is set to be the year that multi-channel (aka omni-channel) marketing really hits the mainstream.

What is Omni-Channel Marketing? Omni-channel marketing is perhaps most easily defined as any marketing activity that spans all available consumer touchpoints, both in terms of outbound communications and the inbound ‘signals’ that consumers send to the organization. Perhaps more importantly, it is a step beyond allowing the consumer to interact with the organization via multiple channels; it’s about ensuring that all those channels work together, in a sensible, seamless manner. Why it matters should be obvious: people want (and expect) to be treated in a way that feels relevant and conversational. What does that look like? Well, to give a simple example, it means ensuring that we don’t send push notifications reminding a user to submit a hotel review on an app, when she has already submitted one online. Delivering that seamless experience is difficult for sure, but, with so many access points, it’s more important than ever. The rise of mobile apps has meant that consumers are interacting with brands across at least two channels (mobile app and web) and often more: brick and mortar stores, for instance. One simply cannot assume that customers are only interacting with us through a single channel - as was true only a couple of years ago.


Table of Contents

Why Omni-Channel Marketing? Table of Contents Introduction

Introduction to the Swrve / Marketo Integration Swrve / Marketo Sync Service Swrve / Marketo webhooks

Use Cases Use Case 1: Targeting & Sending a Push Notification using Marketo data

Use Case Overview Use Case Setup Personalizing Push Notification using Marketo data

Use case 2: Sending & Targeting an In-app Messaging using Marketo data Scenario Overview Scenario Setup

Use case 3: Sending an email with Swrve Scenario Overview Scenario Setup

Getting Started with the Swrve Marketo Integration Assumptions Setup

Appendix 1 : One-off Custom Field Setup Overview Swrve Marketo Sync Service Fields

Appendix 2: Webhook Setup Overview Webhook 1: Push Notification Webhook Webhook 2: Personalize Push Notification Webhook Webhook 3: User Attribute Reflection API


Introduction This document provides detailed step-by-step instructions to run In-app Messaging, Push Notification and email campaigns using Swrve and Marketo together to give the user a seamless experience between web, email and mobile. In this scenario, Marketo provides insights on the users’ behavior on web, and provides the ability to send emails to the user, while Swrve provides insights on the user’s behavior on mobile and the ability to send rich In-app messaging and Push Notifications.


Introduction to the Swrve / Marketo Integration There are two components to the Swrve / Marketo Integration:

Swrve / Marketo Sync Service Swrve / Marketo webhooks

Note: To enable this bidirectional integration both Marketo’s webhooks and Marketo’s REST API are used. Marketo’s REST API is not available in Marketo SPARK edition.

Swrve / Marketo Sync Service The Swrve / Marketo Sync Service passes data from Swrve to Marketo on a daily basis. This service supplies information which can be used to link users between Marketo and Swrve, send targeted personalized Push Notifications and create richer user profiles in Marketo. In order to configure this service Swrve requires REST API credentials and some additional fields added to your standard Marketo Leads. Please see Getting Started with the Swrve Marketo Integration for details.

Swrve / Marketo webhooks A one-time setup process is required to create three simple Marketo webhooks. These webhooks need to be instantiated in the Admin section of the Marketo dashboard. Please see Appendix 2 for details. Your Swrve Customer Success Manager ([email protected]) can assist in this set up process and in end-to-end testing of the functionality.


Use Cases With an integration between two flexible and powerful systems like Swrve and Marketo there are clearly lots of possible use cases. Below are described three common use cases for the Swrve / Marketo Integration.

Use Case 1: Targeting & Sending a Push Notification using Marketo data

Use Case Overview We want to be able to target and send a Push Notification using data that has been collected in Marketo. This Push Notification will be created in the Swrve dashboard. (e.g. for a user who doesn’t open an email from Marketo, we might want to send that user a push notification on mobile a few hours later.)

Use Case Setup 1. Setting up Swrve Push API Campaign

Create Push Notification API Campaign a. In Menu to go Message > Push Notifications b. Select dropdown “Create Push API Campaign - Single User”

c. Go through steps for creating the campaign

On the “Default Content” tab, create the text, deep-links, etc that you want to be sent to the user.

On the “Preview & Test” tab, copy the Push API Key (We will enter this Push API Key in Marketo later in this process.)


2. Create a Smart Campaign in Marketo. This campaign will use the “Swrve Send Push” webhook (described in Appendix 2) to send a request to Swrve Push API.

a. Create a Smart List that targets users who have opted-in to receiving push on mobile. This will be the users who have a valid Swrve ID and have Swrve Push Enabled.

b. Change Swrve Push API Key to the value copied from the Swrve dashboard and add a call to the “Swrve Send Push” webhook.

c. Proceed to schedule the campaign.

Personalizing Push Notification using Marketo data A more advanced version of this campaign involves personalizing the Push Notification for the user inside Marketo. To do this, we need to create a messaging inside our Marketo Smart Campaign Flow We use a Change Data Value component to create in a custom push message.

As above, we need to specify a Swrve Push API Key


Drag Change Data Value onto the campaign Select Swrve_Push_Message as attribute In value input box, you can access any Marketo value through the field notation (e.g.

“Hi lead.First Name lead.Last Name”) Drag Call Webhook onto the campaign Select Swrve Send Push w/ Message from the dropdown

For more information on Push Notifications in Swrve see here.


http://www.swrve.com/product/push-notifications

Use case 2: Sending & Targeting an In-app Messaging using Marketo data

Scenario Overview We want to be able to display a Swrve In-app (rich) Message to a user while they are actually in the mobile app using data that has been collected in Marketo (e.g. for a user who doesn’t open emails but active in the mobile application, we want to send that user an In-app Message). For example, let’s suppose we were attempting to activate users in downtown San Francisco using an email campaign and we want to reinforce this with an In-app Messaging campaign.

Scenario Setup In Marketo, we create a flow which will pass Zip Code to Swrve.

1. Within a flow simply set the Swrve_Name_INTERNAL to the name of the attribute you wish Swrve to have available e.g. “ZIP code”

2. Set Swrve_Value_INTERNAL to the value of the attribute e.g. 94105 or lead.Inferred Postal Code.

3. Finally call the “Update Swrve User Attribute” Reflection API webhook (described in Appendix 2).


4. QA using Swrve QA User page All data send to the Swrve system can be examined on a per-user basis using the Swrve QA Users page. (For example, below we are setting a “MKTO Score” in Swrve to be 70.

Note: Any Marketo data can be reflected to Swrve and made available to Swrve segmentation in this way. Two custom data fields in Marketo will be used to in the Marketo campaign flow with the “Update Swrve User Attribute” webhook:

Swrve_Name_INTERNAL Swrve_Value_INTERNAL

These attributes are listed in Appendix 1.


Use case 3: Sending an email with Swrve

Scenario Overview We want to be able to send an email to a mobile user (who has completed registration on mobile). For example, if we have a mobile user who has had no sessions for 14 days and push notification functionality disabled - and we want to reactive this user in the application.

Note: The Swrve Sync Service uploads data about all registered mobile users on a daily basis to Marketo. This data includes the users’ last active date used in this scenario (“Swrve Last Active”).

Scenario Setup 1. In campaign “Smart List” drop in Email Address. Use “is not empty” value. 2. Drop in “Swrve Last Active” filter. Select “in past before” from dropdown, enter day

value range (e.g. 2 weeks)

Note: We are targeting last active in past before “2 weeks” with an email action. As a best practice, this email campaign should include deeplinks that works on both web and mobile.


Getting Started with the Swrve Marketo Integration

Assumptions This section assumes that:

the Swrve SDK has been added to your mobile application Marketo tagging has been added to your web application

We are assuming that you have already integrated the Swrve SDK into your mobile application and that you are familiar with the Swrve dashboard. If you have any questions about the Swrve SDK integration, please contact your Swrve Customer Success Manager. We are also assuming that you have add the Marketo tagging to your web application and that you are familiar with the Marketo dashboard.

Setup

1. Add swrve.email User Property Send swrve.email as a user property using the Swrve SDK. In order to link together a Marketo Lead and a Swrve user, a common user identifier (email address) is required. Email address should be sent to Swrve as a user property (using the Swrve User API) named swrve.email. iOS code example: (void) onEmail: (NSString*) emailAddress // Register email address with Swrve [[Swrve sharedInstance] userUpdate:@ @"swrve.email" : emailAddress ]; Android code example: private void onEmail(string emailAddress) Map<String, String> attributes = new HashMap<String, String>(); attributes.put("swrve.email", emailAddress); SwrveInstance.getInstance().userUpdate(attributes);

2. Configure Marketo a. Add Custom Fields.

The Swrve Marketo Integration makes use of Lead Custom Fields in Marketo to store interesting fact about users as well for use with webhooks. How to set


http://docs.swrve.com/developer-documentation/api-guides/38784233/#User

up these Custom Fields is described in Appendix 1.

b. Add Webhooks The Swrve Marketo Integration makes use of webhooks to pass data to Swrve and to trigger mobile experiences for users. The set up of these webhooks is described in Appendix 2.

i. Setup Push API Campaign in Swrve ii. Use Push Key in Marketo webhook iii. Using Push Webhook in Marketo Campaign

3. Configure Swrve Sync Service

The backend Swrve Sync process requires a set of credentials and endpoints. a. The Swrve, Marketo Integration makes use of the Marketo REST API.

i. Create an API Only user, and a Launchpoint service as described in the Marketo documentation here.

b. With this completed, you’ll need to supply your Swrve Customer Success Manager with:

i. REST API Endpoint ii. REST Identity API Endpoint iii. Marketo Service Client ID iv. Marketo Service Client Secret

for them to configure the Swrve Marketo Sync Service.


http://developers.marketo.com/blog/quick-start-guide-for-marketo-rest-api/

Appendix 1 : One-off Custom Field Setup

Overview The Swrve Marketo Sync Service passes data from Swrve into Marketo. The service uses the Marketo REST API to periodically upload data about Swrve users that have been recently active into Marketo and for whom Swrve holds an email address. This information is stored in Marketo Lead Custom Fields.

Note: Creating Custom Fields in Marketo requires an administrator user account in Marketo. Typically this process takes less than 10 minutes.

Additionally, Swrve Marketo webhooks use Lead Custom Fields to store temporary information about Leads which is then used in webooks.

Swrve Marketo Sync Service Fields

For any data that is updated by the Swrve Marketo Sync Service, Lead Custom Fields are required. Marketo’s documentation for new Custom Field create can be found here. At the minimum the following Lead Custom Fields should be created. These are the fields which are updated by default by the sync service. (*Custom Fields may take some time to load when created)


http://developers.marketo.com/blog/create-a-custom-field-in-marketo-and-update-this-field-via-api/

Field Name Display Name Field Type

swrveID Swrve ID String

swrve_app_store Swrve App Store String

swrve_date_joined Swrve Date Joined Datetime

swrve_device_name Swrve Device Name String

swrve_language Swrve Language String

swrve_last_active Swrve Last Active Datetime

swrve_milliseconds_spent Swrve Milliseconds Spent Integer

swrve_os_version Swrve Os Version String

swrve_push_enabled Swrve Push Enabled Checkbox

swrve_session_start_count Swrve Session Start Count Integer

swrve_timezone_name Swrve Timezone Name String

Additionally, the following Lead Custom Fields are used by webhooks:

Field Name Display Name Field Type

swrveNameINTERNAL Swrve_Name_INTERNAL String

swrveValueINTERNAL Swrve_Value_INTERNAL String

swrvePushAPIKey Swrve_Push_API_Key String

swrvePushMessage Swrve_Push_Message String

Note: All of these fields need to be created in order to use the Swrve Marketo Integration.


Appendix 2: Webhook Setup

Overview Webhooks are used to pass information from Marketo to Swrve. These need to be set up as a one-time process. For each of these webhooks, you’ll need to:

Go to Admin > Integration > Webhooks Click on Webhook Actions > New Webhook Follow the steps listed for each webhook.

Note: Creating webhooks in Marketo requires an administrator user account in Marketo. Typically this process takes less than 10 minutes.

At the end of this process, you’ll have created three webhooks and should see something similar to what is shown below.


Webhook 1: Push Notification Webhook

Webhook Name Swrve Send Push

Description Send a push notification using the Swrve Campaign ID set in Marketo Attribute Swrve_Push_API_Key

URL https://service.swrve.com/push?push_key=lead.Swrve_Push_API_Key:default=edit me&user=lead.Swrve ID:default=edit me

Request Type POST

Response type None


Webhook 2: Personalize Push Notification Webhook

Webhook Name Swrve Send Push w/ Message

Description Send a push notification using the Swrve Campaign ID set in Marketo Attribute Swrve_Push_API_Key and personalized message.

URL https://service.swrve.com/push?push_key=lead.Swrve_Push_API_Key:default=edit me&user=lead.Swrve ID:default=edit me&message=Swrve_Push_Message

Request Type POST

Response type None

Note: This webhook is very similar to the previous webhook, with the addition of a message parameter for customizing the campaign.


Webhook 3: User Attribute Reflection API

Webhook Name Update Swrve User Attribute

Description Update Swrve User Attribute using Swrve_Name_INTERNAL and Swrve_Value_INTERNAL

URL https://<app_ID>.api.swrve.com/1/user?api_key=<api_key>&user=lead.Swrve ID:default=edit me&user_initiated=false&lead.Swrve_Name_INTERNAL:default=null=lead.Swrve_Value_INTERNAL:default=null

Request Type GET

Response type None


Swrve / Marketo Integration...Swrve / Marketo webhooks A one-time setup process is required to...

Documents

Transcript of Swrve / Marketo Integration...Swrve / Marketo webhooks A one-time setup process is required to...