In this post, we’re going to cover the hurdles an McGaw.io client faced when trying to integrate Marketo with Segment. We’ll explain how we overcame these challenges and ultimately helped the client make their launch date.
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 if you have to deal with a similar scenario.
First, a Little Background…
Our client wanted to be able to send automated emails to people who had taken certain actions 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.
After researching all of their options, our client discovered that Segment was the best tool to help them implement behavior-based automated emails. As soon as they began trying to integrate Segment with the rest of their marketing stack, however, they knew they did not have the experience to get it right in time to make their aggressive launch dates.
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, the client’s go-live date was right around the corner. They knew they needed to use Segment if they were going to get the most out of their launch. The only way out of this catch-22 was to find someone who could train them quickly.
Which is where McGaw.io came to the rescue
They found us through our blog and we stood out to them because we’re a Segment Certified partner (one of their first partners, in fact). In the end, we helped our new client get their tools integrated and trained their team on how to use Segment (and Segment with Marketo) more effectively.
What followed was a successful launch for the client and a revelation for us about how marketing teams should go about integrating Marketo with Segment.
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 come to 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: (Check out our online course to learn more about all of these things)
- Events – actions that website visitors take or important activities
- Properties – attributes of a specific event
- Triggers – the action that enables the event to be recorded by your marketing tools
- IDs – Actual web markup that goes on specific web pages, buttons, forms, or links
Now if you’re confused about the differences between events and triggers, that’s normal. Let’s take a simple example:
We could create an event called “viewed page,” and the trigger would be when a specific URL (web page) fully loads.
For example, when the web page contact.html fully loads, our marketing tool records that user 2643266 “viewed page.” Or, when someone clicks on a signup button, it records “signup button clicked” for that respective user, as well. Make sense?
Now, the first thing we do when we start a marketing integration project for a client is to create a specification guide, also known as taxonomy. (You can grab our spec template here and learn how to make one of these in our webinar.)
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’ve probably guessed, we created a unique specification guide for our client so that they had a single sheet everyone could 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 specification exercise once is very valuable for any marketing department that’s beginning to experiment with martech tools.
It can ensure you don’t throw away months of bad data later on and, more importantly, you’ll be making correct data-driven decisions 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 process.
Cracking into Marketo
Although we have a lot of experience working with Segment, we’re less experienced integrating Marketo with Segment. To tackle this problem, we spent time a lot of time studying the Segment and Marketo integration documentation.
We found that there are very strict restrictions on how you can integrate Marketo with Segment. This was important to note since these problems don’t normally occur with other platforms. We’ll cover these Marketo restrictions, specifically as they relate to Segment, later on in this post.
Discovering an issue in Segment
We encountered an issue where data was not being “sent” properly. We worked through all the things that could go wrong and validated that everything worked 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 so we could test the issue across multiple integrations. 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 wasn’t. 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.
We spent hours trying to debug the issue with no luck.
At this point, we knew we needed Segment phone support.
The Segment plan we were signed up for 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 user interface (UI) was showing something different than what was saved on the backend.
This issue had to do with how API (application program interface) 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. Hence the term “key.” Think of it as a key that unlocks your access to the software. You take this key and enter it into your Segment account — and voilà, the two software installations can now talk to each other. In this case, it allowed Marketo and Segment to communicate back and forth.
The exact problem was a glitch where 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. Without the amazing help from Segment’s team, we would never have been able to see this issue. Their team was able to hop on a call with us, show us the bug, and help us get things back on track.
Bugs are a fact of life in software. This is why it is so important to have great support teams on your side :)
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 an 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 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 exactly
- Match the Marketo UI key with the Marketo integration key
- Mapping Segment Identify calls & traits
- Make sure syntaxes are an exact match
Let’s look at the first three 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 events or event properties that are passed to its platform. Each event and property needs to be created as a custom field and mapped in Segment.
To do this, log in to Segment, go to Sources and select your source, then 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. A typical event we would record is when someone creates an account.
The image below is what you see if you click on the event “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.
Match Marketo UI key and Marketo integration key
You’ll also want to ensure you’ve set Marketo to have the same primary key 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.
Here is the Custom Activity defined in Marketo:
Copy the API Name value and paste it into the Marketing Field Name in Segment (under Destinations). Copy the ID from the Marketo Custom Activity and paste it in Segment.
Here is how the mapping should look for this part in Segment:
Be sure to check the “Set as Primary Key” checkbox. You only set this primary key on one of the Segment Event property/Marketo Field Name sets, but you can add multiple properties to Segment events on the Segment Event mapping screen:
Mapping Segment Identify calls & traits
Next, you need to set up any traits from Segment identify calls in the Marketo Custom Fields section of Segment:
After you click on the Marketo Custom Fields section, you’ll get this screen:
Fill in each field to finish setting up traits from Segment identify calls by clicking on Add Another Segment/Trait and following the steps outlined above. You want to be sure that the syntax of any properties being passed to Segment is an exact match to 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. We believe that our close relationship with most of the martech software companies out there is a huge plus when it comes to tackling advanced problems. In this case, our friends at Segment teamed up with us to get the client on track to hit their pressing deadline.
Despite this hiccup, Segment is a great tool. Without Segment, marketing automation and getting useful analytics would be a nightmare. In fact, Segment is the “glue” in our recommended marketing technology stack.
If you’re struggling to integrate Marketo with Segment, this post has hopefully 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.