Marketo Integration Guide
Marketo Rules!
Setup
Customers set up the Marketo integration following the steps [here] (https://wistia.com/doc/marketo#get_set_up)
If you are setting up your own Marketo integration, you’ll want to follow the steps in our documentation as well. They’re great! If you just want a connected integration to test something out with, you can use the Marketo integration set up on this Wistia account for support team testing.
If you are working with a customer to troubleshoot their integration, you’ll want to verify that they’ve followed these steps as well, and that the following things are in place. Presented in checklist format…
Common Gotchas
Their plan has access to Marketo
We want to check that a customer is on a plan that has access to the Marketo integration. Does it have access? We can look on their integrations page to find out.
Which version of Marketo are they trying to connect?
The current version of the integratin uses the Marketo REST API. The original version of the data integration uses the Marketo SOAP API. We used to have a version of the Marketo integration that was a Turnstile-only integrations. Some customers still have this version. (how do I easily find that out?)
Know which version we are working with! Our current documentation and setup is for the Marketo REST API, but some folks may still be on the old versions.
API keys are entered correctly
Some random numbers and strings are entered in the Account integrations field. Are the API Keys in the fields the right API keys? Usually the are. If the integration is “failing to connect” or “disconnected” on the integrations page… they should be double checked.
Munchkin is on the page
Is the video embedded on a page where the Marketo Tracking script munchkin.js is also included?
The data integration sends information as the video plays back. Munchkin.js must be on the page for this to work. You can check this by looking at the page source code for munchkin.js or by looking in the network tab for a request to munchkin.js.
For Turnstile: Provider & List are set as Marketo and some value
While setting up in the customize menu, the Turnstile should have a Marketo list selected, or otherwise a list value of “none”. Either way, gotta have a list and list value selected other than “–” for Turnstile captured leads to be sent through to Marketo!
Event workflows: have the events occurred?
A relatively common issue that is noted in our help page, but will catch some folks.
In order to run a workflow in Marketo based on an event trigger, that event must have occurred. For example, to run a workflow on Wistia Video: 50% watched, that video must have been watched 50% and registered with Marketo.
Note about Firefox incognito mode and Marketo
Firefox implements “tracking protection” such that Marketo Munchkin Javascript is not loaded in incognito windows. https://developer.mozilla.org/en-US/Firefox/Privacy/Tracking_Protection
It’s usually good strategy of testing things out to use an incognito window but in this case it will not work as expected. You’ll get an initial play event, but will not get 25%, 50%, etc if you’re testing Marketo integration in Firefox.
The checklist, again
To reiterate, this is the basic list of things you want to check
- The Plan is a Marketo Plan
- The Marketo Munchkin.js is included on the page with a Video
- Credentials from setup steps have been entered in Wistia and the integration says it’s “Connected”
- Turnstile has Marketo and a selected value for “Provider” and “List”
Does a viewer need to submit a turnstile for this to work?
Yes, you submit on a turnstile once, and we can then identify you to marketo… and we can continue identifying you to marketo forever after, no matter whether you fill out further turnstiles.
- The turnstile needs to have a value selected for List. Don’t want a list? Select the ‘None’ value.
How It All Works
Let’s be honest, this is probably why you’re here. Someone has done all of the setup stuff and it seems right a far as you can tell, but something is off. What is it? A good rule of thumb is to start with asking yourself what you’re missing, or what you don’t know about a scenario. Let’s start by making sure you’ve got a good mental model of how things work under the hood a little bit.
Communicating with Marketo
Our communications with Marketo are unidirectional. We send information to Marketo. Marketo does not send data back to Wistia. The basic paths that this takes are:
- Turnstile entries are sent to the Wistia app, which sends the CapturedEmail (created by Turnstile) to the Marketo REST API (and previously SOAP API)
- E-v1.js sends player events (play, 25%-100% watched, click/conversion) using the Marketo Munchkin javascript library in the browser. You can watch this in the network tab by filtering for requests by
visitWebPage.
Foreign data
In Marketo’s case, foreign data is the value of a Marketo tracking cookie that we’ll use to try to send Wistia data to the right location in a Marketo.
Foreign data usually refers a set of identifying data or tracking cookie from a MAP provider that is detected by Wistia then sent paired alongside with Wistia data to send to the right place.
Marketo uses a browser cookie to do much of their identifying/tracking work, so for Marketo we save the value of that Marketo cookie as our “foreign data”.
Also related to foreign data… Turnstile submissions create a new CapturedEmail object in the Wistia CapturedEmail table in our database. We save the “foreign data aka marketo cookie value” on that CapturedEmail so that it can be passed to Marketo when we create (or update) a lead in Marketo from that Turnstile submission.
The cookie has two parts which are a token and an id.
w = Wistia.api("hashed_id");
// returns a handle to the wistia player object as "w"
w.foreignData()
// { marketoCookie: "id:354-URC-800&token:_mch-wistia.github.io-1484590436847-96057" }
Events via the player
In addition to turnstile submissions, we also send data to Marketo as activity happens within the player.
Marketo’s munchkin.js is a Javascript library similar to what E-v1.js is to Wistia. You can verify if it is on a page by typing Munchkin into the console and seeing if the variable is defined.
> Munchkin
< Object { ASSOCIATE_LEAD: "associateLead", CLICK_LINK: "clickLink", VISIT_WEB_PAGE: "visitWebPage"}
> DoesntExist
< Uncaught ReferenceError: DoesntExist is not defined at <anonymous>:1:1
All the “integration” between our E-v1.js and the Marketo javascript that happens in the browser occurs in a file within E-v1.js.
We use public Munchkin javascript APIs to send through information to Marketo about video playback.
All our events are listed in Marketo under visitWebPage because that is the API we send the events to.
Troubleshooting
Now that we know how things fit together in theory, we can verify if that’s actually how they’re working in practice. If we can discover more specific information about what is not working that will give us a good idea where to go next.
Checks that can be done in the browser!
Here we check that the player has been initialized with the correct plugins to send info to Marketo, and is sending em.
Ensuring that the foreign data needed to link Wistia + Marketo viewers is being set properly
We’ll check a couple things in order.
First, that we have the marketo integration.
Second, that foreigndata that the player knows about contains a value for marketoCookie
Third, if the video has a turnstile we can check whether the Turnstile plugin called “requireEmail-v1” knows that it has “marketo_v2” as a provider.
All these steps can be checked in the console, so here’s how we can do that:
// a handle on the video
> w = Wistia.api("ur_hash_id")
< n {_implVersion: 1, _playlistIndex: 0, _attrs: Object, params: Object, options: Object…}
// checking that we have the marketo integration
> w.data.media.integrations
< Object { marketo_v2: true }
// checking that foreigndata is set
> w.foreignData()
< Object {marketoCookie: "id:354-URC-800&token:_mch-wistia.github.io-1484595485644-10261"}
> // One other thing we could check if the video has a turnstile
> // is that the Turnstile knows it has "marketo_v2" as the provider
> // If this viewer is already identified to Marketo, a Turnstile isn't a necessary part of the process for further data to be passed through
> w.plugin["requireEmail-v1"].options.provider
< "marketo_v2"
Checking in the Network tab that events are being sent through to Marketo
It doesn’t really do us all that much good to see that things are setup or that things are as they should be within the player if we’re not also verifying that the things we expect to happen are actually happening. We want to check the network tab to see that requests are getting sent through and hitting the Marketo URL that records the tracking.
Most information that we send Marketo is via query string parameters attached to the end of the Marketo visitWebPage webevents URL. The has a format like https://354-urc-800.mktoresp.com/webevents/visitWebPage – the easiest way to look for it is a name starting with visitWebPage in the network tab.
On the page where your video lives, let’s open up the network activity tab in your browser of choice and filter by visitWebPage
We’re mostly interested in the parsed query params, which can be found at the bottom of the detail pane for this request. The example data we’re looking for is something like this:
_mchNc: [1484598479549]
_mchRu: [- Wistia Video: "Kevin gets an applause" - 25% Watched]
_mchId: [354-URC-800]
_mchTk: [_mch-wistia.github.io-1484598282101-56066]
_mchHo: [wistia.github.io]
_mchPo:
_mchPc: [https:]
_mchVr: [151]
_mchRe: [https://wistia.github.io/aardvarkgarden/integrationplayground/marketo-playground.html]
The brackets in the above text indicate things that will be specific to your page, video and/or activity, but are the sort of things we’re looking for.
The value of _mchId and _mchTk together are the values stored in a Marketo tracking cookie, so they are the most critical points of info for making things connect correctly.
// Inspecting a marketo cookie just because curiosity
Wistia.cookie('_mkto_trk')
"id:354-URC-800&token:_mch-wistia.github.io-1484598282101-56066"
Captured Emails
- Checking that captured emails are being sent from our server to Marketo via our integration code
Here’s where things start to get really advanced, since this one will require access to the application console or the production database via Sequel Pro or something. If you have never done this before, pair with someone from the Kodiak Squad, Bobby, or an Advanced Support Specialist to get the info you need. Okay, now that the disclaimer is out of the way, here’s the gist of what you’re going to do: find the CapturedEmail record in the database, verify that it has info that looks reasonable (i.e the fields look okay), and that it has a synced_at date.
Captured emails are a bit weird in that there’s no obvious association that fits them under an account, so you’ve got to search the entire CapturedEmail table, and filter based on some information. The simplest information to filter on is the email (as a string) and the account_id (as an integer). If you’re doing this in the application console, it can be done pretty simply this way:
account = Account.f('account key') # Note: make sure you put in the account key
email = "person@place.com" # Note: put the email you want in here
CapturedEmail.where(email: email, account_id: account.id) #Note: this returns an array
That will return an array of all the captured emails for that account that match the email address you’re looking for. What you do from here kind of depends a bit. If you’re just verifying this should be all you need. If you want to try syncing the email again, we can try that here.
our_captured_email = CapturedEmail.find(00000) # Note: use the id of the object in the array returned before you wanna work with
our_captured_email.sync
Assuming we succeeded at trying to sync this, you won’t really see much. If you see an error, that’s bad, and you’re officially off the beaten path with this one. If there were no errors, you can check in with the customer to see if it worked. You can also check Bugsnag to see if there was an error syncing the email that we received from Marketo when trying to sync it. This is uncommon, but possible.
Stories of CapturedEmail adventures off the beaten path can be read here… https://github.com/wistia/wistia/issues/4239
Resources
Testing the Marketo integration Video:
https://jgbsilberg.wistia.com/medias/dedfdf3ucu
Working with Triggers in Marketo:
https://jgbsilberg.wistia.com/medias/bjv4h2zokp
_marketo.coffee models/vendor.rb models/integration/integration.rb models/vendor_adapter/marketo_adapter.rb models/vendor_adapter/marketo_v2_adapter.rb helpers/integrations_helper.rb