Your initiation to the HubSpot Integration begins now.

Setup

Initial requirements

Before you get started with running though all the stuff to understand how this integration works, let’s go over what you’ll need to get started.

  1. A HubSpot Account
  2. A Wistia account
  3. A video
  4. A web page

Once we’ve got all this stuff, we can run through how to setup your Wistia and HubSpot stuff to play nicely together. This setup guide will serve as the initial auditing steps for someone’s integration, as you should verify that each of these things exists and is configured properly.

First step: turn on the integration

Within your Wistia account, you’ll want to go to the integrations section of your Account Settings and select “HubSpot” from the list of integrations (it’s near the bottom). Input your Hub ID and “Connect” – keep in mind that the option to connect will only show if you have a Wistia plan that allows for Marketing Automation Provider (MAP) integrations. If you do not have such a plan, the option to connect will be replaced with a button that says “Upgrade to connect.”

Your Hub ID can be found in the top right of your HubSpot portal whenever you’re logged into your HubSpot account (nice and easy). When you add that to the integrations page in Wistia, it’ll redirect you to your HubSpot account (you will have to login if you are not) where you will authorize the integration to access your HubSpot account. Once it’s connected, you’ll be redirected back to your Wistia account.

The second thing you’ll need to do is enable the integration from the HubSpot side, which you can do by selecting “Integrations” from your HubSpot account menu, and then “Connect with Wistia.” The page it takes you to needs an API token from Wistia. You could use your Master Token, but it’s safer to make a token with create, read, update and destroy (CRUD) access for your Wistia account. The reason for this is that it gives you the ability to revoke access to that token at a moment’s notice if you need to. You probably won’t, but it’s an easy enough safeguard to have to you might as well.

Second step: ready your media

Okay – so we already covered that you’ll need a video for this, but we haven’t yet prepared readying that video for prime time. This step is pretty simple, and is something we generally want people to be doing anyway. Within the Timeline Actions portion of Customize for your video, add a Turnstile and make sure the HubSpot integration is enabled. Pretty simple.

Fun fact: if you don’t care about capturing emails, the Turnstile step is somewhat optional – your medias will still know that you have the MAP integration and be able to run parts of it without a turnstile. Of course the downside is that you won’t be able to get perfect information since lots of folks will be unidentified and won’t be unified as Wistia visitors and HubSpot contacts inside your HubSpot account.

Third step: ready your web page

For our web page, there are two things we need to make sure happen: the video gets embedded and the HubSpot tracking code is added. You can find instructions on adding the HubSpot Tracking Code from HubSpot’s docs. The key piece of this is being able to copy the tracking code from your “Reports Settings” section of your HubSpot portal. That code will look something like this (though it’s slightly different for each HubSpot account):

<!-- Start of HubSpot Embed Code -->
  <script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/2813758.js"></script>
<!-- End of HubSpot Embed Code -->

Fourth step: watch your data come in… hopefully

The setup is pretty easy, and our own help page for HubSpot covers most of this stuff in a little more detail with some screenshots, so make sure you give that a look!

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 HubSpot

Our communications with HubSpot are unidirectional. We only really send information to HubSpot (sometimes they ask, sometimes we just send it). The forms that this can take are:

  1. Form submissions using the HubSpot forms API
  2. Foreign data to associate Wistia viewers with HubSpot contacts
  3. Heatmap information
  4. Events via the player
Form submissions

Form submissions are the things we leverage to send new contacts over to HubSpot. You can see where we use this in the application if you’re a curious kitty. The accomanying documentation for the HubSpot forms API can be found in their developers documentation. This is specifically the step that makes sure Wistia visitors can be properly tied to HubSpot contacts.

Foreign data

Foreign data is more or less what it sounds like. We attach some information to a CapturedEmail in Wistia, which is the object we created based on Turnstile submissions, that includes information from both Wistia and HubSpot that’s critical in making sure we can communicate about prospects with HubSpot fruitfully. The two most critical pieces of data stored here are the visitor_key and the hutk (basically HubSpot’s version of a visitor key). The magic for this happens from a file within E-v1.js.

Heatmap information

Part of the HubSpot integration is displaying heatmaps for views within your HubSpot portal. This works by having HubSpot leverage our stats API to access heatmaps for sessions. This relies on the foreign data step succeeding.

Events via the player

In addition to turnstile submissions, we also send data to HubSpot regarding the other activity happening within the player, such as the percentage watched. This magic also happens from a file within E-v1.js.

Troubleshooting

Alright, so now you have a good idea of the inner workings of the integration in addition to how to set it up, let’s walk through some ways to test, troubleshoot and audit a Wistia + HubSpot integration. I’ll be going through these by tactic and not by symptom – going back to a tip from before, it’s important to identify what you don’t know, and the answer to that will point you in the direction of which tactics to start with.

Figuring out if your Wistia embed knows that it should have the HubSpot Integration and be using it

So, as covered before in the second setup step, part of the integration works without having to worry about turnstiles. Or, well, it’s supposed to. Sometimes it does not, though this is rare. Because these work independently of each other, there are two things you need to check.

  1. The Turnstile Plugin: If the video is supposed to have a turnstile, you should ensure that the plugin is present and knows it should be using HubSpot. To do this, you can play around with the player API. Here’s how to check for the Turnstile plugin on a video:
w = Wistia.api("hashed_id") // make sure you're using the hashed id of your video here, not just literally "hashed_id"
w.plugins

This will return a javascript object that contains one entry per plugin. They’re labeled in a hard-to-parse way, but expanding the objects until you can find a pluginName key will help you spot what you’re looking for. Inside that same object, you’ll want to look at its options – inside the options you should see something denoting that it’s using the HubSpot provider. If it doesn’t show that, you might have found the source of your problem!

  1. The HubSpot MAP integration: Videos on a page know they’re supposed to be using a MAP integration by looking at the media’s integration data. similarly to Turnstile, you can double check for its existence by utilizing the javascript console:
w = Wistia.api("hashed_id") // make sure you're using the hashed id of your video here, not just literally "hashed_id"
w.data.media.integrations

This will also return a javascript object, and for each integration on the associated account you’ll see a boolean value. If you want the HubSpot integration enabled, the boolean value should be true.

Making sure that communication is being sent to HubSpot from the page that the video is on

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. Most information that we send HubSpot happens by adding query string parameters to the end of the URL of the HubSpot tracking pixel. The URI of the HubSpot Tracking Pixel is https://track.hubspot.com/__ptq.gif – this will be the URI we’ll be looking for.

On the page where your trouble lives, let’s open up the network activity tab in your browser of choice. From there, we will want to filter based on the aforementioned tracking pixel URI. You are likely going to see a decent amount of activity here if the person is doing lots of HubSpot tracking. This is a good sign, generally, in that it means the HubSpot tracking code is working well on this page outside of the context of the Wistia embed.

The network requests we’ll be concerned with will be easy to spot in that the first query parameter listed will start with id=Video, followed by things specific to the video (its name, generally). If you click that network entry, you’ll see a whole boatload of information. 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:

id:Video "[title]": [action]
n:Video "[title]": [action]
rcu:https://site.com/video-page
r:https://site.com/referring-page
t:[page title]
i:wistia_visitor_key=[visitor key]

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.

Ensuring that the foreign data needed to link Wistia + HubSpot contacts is being set properly

If you’re sensing a theme here, that’s because there is one – a lot of the steps we have here require a little extra finesse and digging, since it’s all the “under the hood” stuff. This is no different. Fortunately, similar to checking if the video knows it’s supposed to have integrations, this verification step only requires a little javascript code to work:

w = Wistia.api("hashed_id") // make sure you're using the hashed id of your video here, not just literally "hashed_id"
w.foreignData()

There’s a secret player API method that will return the foreign data for a video. This is really helpful since checking this is a pretty crucial step. In an ideal world, here’s what that foreign data will return for a HubSpot integrated video:

Object {page_url: "https://wistia.com/library/down-and-dirty-lighting-kit", page_name: "The Down and Dirty DIY Lighting Kit | Wistia Learning Center", hubspot_hutk: "039454198c53efded83cf64eaf44b647", wistia_visitor_key: "v20150227_0f41c47b-b5e0-4529-ad81-03f52baeb460", email: "jordan@wistia.com"}

Per usual, keep in mind that these values will be different for each page/person/etc, and that you might not always have the email address in there (that’s a turnstile specific thing), but the key pieces of that puzzle are the hutk and wistia_visitor_key values, since those are the things that really make the magic happen.

How can we make sure we’ve tried to send emails captured via Turnstile over to HubSpot?

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 HubSpot when trying to sync it. This is uncommon, but possible.

Reference

There are a lot of reading materials that you can look through that will help beyond what this guide explicity inlcudes. Here’s a list of some related items that can help you on your journey:

  • Wistia HubSpot help page: https://wistia.com/doc/hubspot
  • HubSpot Academy for the Wistia integration: https://knowledge.hubspot.com/articles/kcs_article/integrations/how-to-integrate-hubspot-and-wistia
  • Generic advanced turnstile integration troubleshooting: https://github.com/wistia/customer-happiness/blob/master/knowledge/integrations/advanced-turnstile-integration-troubleshooting.md
  • General HubSpot integration info: https://github.com/wistia/customer-happiness/blob/master/knowledge/integrations/hubspot.md