In this post, we’re going to cover the difficulties an Effin Amazing client faced when trying to integrate Marketo with Segment. We’ll talk about how we helped them make their launch dates and how we overcame issues that confused even the Segment support team. Needless to say, we dove straight into this mess and came out with a clean solution for all who’ve been (or currently are) stuck in a similar situation.
This post is going to get quite technical at times. But that shouldn’t stop you from seeing what can, and often does, go wrong when integrating marketing tools. We hope that by reading this post, you’ll be able to avoid a lot of the issues we faced when dealing with a similar scenario.
First, a little background…
Our client wanted to be able to send automated emails to people who had shown certain behaviors while on their website.
This is a common desire for most online marketers. Take, for example, someone who visited a website and added products to their shopping cart, but then left the site. For this type of behavior, you might want to send an email reminding the person that they still have items in their cart.
Our client’s research led them to believe Segment was the best tool to help implement behavior-based automated emails. However, as soon as they began trying to integrate Segment with the rest of their marketing stack, they ran into trouble.
So, they looked for help.
Initially, the client wasn’t able to find a Segment implementation partner because very few agencies offer this particular service.
To make matters worse, they had aggressive launch dates. They knew they needed to use Segment if they were going to get the most out of their launch, but they had a difficult time understanding how to make Segment work for them. The only way out of this catch-22 was to find someone who could train them quickly.
Which is where Effin Amazing came to the rescue
They found us through our blog and decided to work with us. We stood out to them because we’re a Segment partner (one of their first partners, in fact). In the end, we helped our new client get the tools integrated and trained their team on how to use Segment more effectively.
What followed was a successful launch for the client and a revelation for us about how marketing teams should go about integrating Segment and Marketo.
Here’s a look at what we did and the problems we encountered along the way…
Laying the groundwork
Segment and many marketing technology tools tend to be “event-based”. A typical website user or visitor will visit a website and navigate through pages, click on buttons, and fill out forms. All these unique actions can be thought of as “events” and events can set off “triggers”. This is common martech lingo that you’ll hear a lot about in this post.
Here’s some terminology that you’ll want to get used to:
- Events – actions that website visitors take / important activities
- Properties – attributes of a specific event
- Triggers – the action that enables the event to be recorded by our marketing tools
- IDs – Actual web markup that goes on specific web pages, buttons, forms or links
Now if you’re confused between events and triggers, that’s normal. Let’s take a simple example:
We’ll create an event called “viewed page”, and the trigger would be when a specific URL (webpage) fully loads.
So, in this case, when the web page contact.html fully loads, our marketing tool records that user 123 “viewed page”. Makes sense?
Now, the first thing we do when we start a marketing integration project for a client is to create a specification guide.
This gets everyone aligned on what to call certain events, triggers, and other important details. As you can imagine, when you set up your tools, you’ll want things named consistently, otherwise, you’re in for a world of pain.
To do this, we created a taxonomy that would describe the events (actions the users take) and the user identity attributes (things we know about the user). Here’s an example spreadsheet:
(If you want to learn more, check out our SlideShare presentation about Segment and spec guides.)
As you probably have guessed, we created a unique specification guide for our client so that they had a single sheet everyone can refer to that had all their events, triggers and IDs clearly named.
If your company decides to work with us, this will be a process that we’ll guide you through. As a matter of fact, just doing this specific specification exercise once is worth an immense amount of value for any marketing department that’s beginning to experiment with martech tools.
It can end up making sure you don’t throw away months of bad data later on and more importantly, you’ll be making correct data-driven decisions starting from day one (instead of dead wrong ones!). Please, feel free to contact us if you would like us to consult your company on this very important starting process.
Cracking into Marketo
Though we have a lot of experience working with Segment, we’re less experienced integrating Marketo with Segment. To tackle this problem, we spent time reading the Segment and Marketo documentation, of which there was a lot.
We found that there are very strict restrictions on how you can integrate Segment with Marketo. This was important to note since these problems don’t normally occur with other platforms. We’ll cover these restrictions, specifically as they relate to Segment, later on in this post.
Discovering a bug in Segment
We encountered was an issue where data was not being “sent” properly. We worked through all the things that could go wrong and validated that everything worked well on our end.
Our hunch was that there was a problem with Segment itself. The problem became more confusing when we reached out to the Segment support team and they couldn’t work out the issue either.
Luckily, we had multiple “sources” set up in Segment. A source is where data is sent from when it goes into Segment. For example, your website would be a source. In this case, we had a testing (staging) source and a production source. It was this setup that let us know the problem wasn’t on our end.
The test source was working, but the production source was causing all the problems. This didn’t make sense, because both sources were using the same settings. We combed through our setup a few more times and we still couldn’t figure out the problem.
A week went by, where we spent hours upon hours trying to debug the issue and we still had no luck.
At this point, we knew we needed Segment phone support.
The Segment plan we were signed up to doesn’t normally allow for phone support. But because of our partnership and the nature of the issue, Segment was eager to get a phone call going. Through our combined efforts we were able to discover a bug where the UI (user interface) was showing something different than what was saved on the backend.
This issue had to do with how API keys were being stored. You need to use an API key to do integrations. An API key is a unique string of characters that validates that you are the rightful account owner for a specific software license. Hence, the term “key”. Think of it as a key to unlock your access to the software. You take this key and enter it into your Segment account—and voila, the two software installations can now talk to one another. In this case, it allowed Marketo and Segment to communicate back and forth.
The exact problem was that for some reason Segment was storing the API code with a space in front of the key. This, of course, prevented the integration from working. What was making the problem difficult to solve was that the Segment UI wasn’t showing the space!
Once this issue was fixed, everything in relation to Segment began to fall into place.
What you need to know about integrating Marketo with Segment
One of the hardest parts of this process was figuring out how to make Marketo work with Segment. Marketo is a fairly established martech platform, so we expected it to play nicely with Segment. It turns out that this wasn’t the case.
In fact, for Marketo to work properly with Segment, we had to make sure certain specific criteria were being met.
Here are the criteria Marketo requires:
- Ensure that Cloud Mode is enabled
- Identify the user in Marketo before sending track calls
- Map all events correctly
- Match the Marketo UI key with the Marketo integration key
- Make sure syntaxes are an exact match
Let’s look at each of these in a bit more detail.
1. Enabling Cloud Mode
Segment has two connection modes, “Device Mode” and “Cloud Mode.” If you want Marketo to work with Segment, you need to make sure you’ve enabled “Cloud Mode.” If you set Marketo to “Device Mode,” Marketo is going to ignore all the calls Segment sends over.
To enable Cloud Mode in Segment, navigate to Sources, click on the Marketo integration and look for the Connection Mode option. Once there, be sure to switch to Cloud Mode.
2. Identifying the user in Marketo
Almost all event-based martech tools use a .track() call to record event-based actions. In order for Segment to send track calls to Marketo, you’ll need to identify the user in Marketo. If you miss this step, you’ll get a “User Not Found” error.
To identify a user in Marketo go to Admin > Data Management > Create a new field. Enter these values for the three required fields:
- Type: String
- Name: User ID
- API Name: userid.
You then need to make sure the Custom Events and Properties are mapped correctly before sending data. If just one event is mapped incorrectly, it will result in the integration call being ignored by Marketo.
3. Mapping events correctly
Unfortunately, Marketo doesn’t “automagically” detect event properties that are passed to its platform. Each property needs to be created as a custom field and mapped in Segment.
To do this, log into Segment, go to Sources and select your source, go to the Debugger and click on the event in question.
Let’s go over an example of how this works. We’ll assume that we’re running a Vacation Rental website and a typical event we record is when someone creates an account.
The image below shows an event name, “rental inquiry – created account”, and the respective property, “tracking_status” in Segment.
Defining and mapping the event name “rental inquiry – created account” and property “tracking_status” exactly as passed from Segment to Marketo is essential to firing the data properly.
4. Matching the Marketo UI Key with the Marketo Integration Key
Finally, you’ll also want to ensure you’ve set Marketo to have the same Primary Key as what you have set in Segment.
To find your primary key in Marketo go to Admin > Custom Activities. The apiName (API Name) of the attribute is the primary key.
Copy the API Name value and paste it into the Marketo Custom Activity ID in Segment (under Destinations).
Be sure to check the “Set as Primary Key” checkbox.
You also want to be sure that the syntax of any properties being passed to Segment is an exact match as the custom fields you’ve set up in Marketo.
If you’d like to delve deeper into the requirements for integrating Marketo and Segment, you can read the documentation provided by Segment.
Clients come to us looking for all sorts of solutions to their marketing and analytics problems.
Sometimes their problems are relatively straightforward. Other times there are a lot more challenges than expected.
This post details the latter. But, of course, challenges don’t mean the task is impossible, and we managed to get everything working in the end.
If you’re struggling to integrate Marketo with Segment, hopefully, this post has provided the insight needed to get things working. Please let us know if you run into any obstacles and we’ll be sure to update this post to make it more clear. We’re also available to help you with any martech integration challenges.