How to make successful integrations

  ·   Feb 07, 2022

Integrations between platforms are all about communication. You and your integration partner need to figure out how to talk to each other.

Short about us

Adlede provides contextual advertising as a part of the programmatic advertising market. We analyze content, mostly from news publishers, and provide content information to the ad market. We are integrated with SSPs and DSPs in the ad market, as well as with publishers and intelligence partners that enriches content for us. Adlede gives an opportunity to cookie-free advertisement respecting the personal integrity of the reader.
Also—we make ad money flow to manually vetted publishers supporting high quality journalism.

Basics

You can say that we have got some experience of how to, and how not to, make integrations.

Technically, it should be easy.

Often a REST API is used for the communication, and that part is relatively simple. You need the endpoint URL and credentials so you can identify yourself. You use the HTTP methods GET, POST, PUT and DELETE to make actions. You send your data as a file of an agreed format, often .json or .csv.

Another way could be to set up an S3 bucket or other cloud storage, where one partner has write access, and the other can read.

But, this is the easy part—these protocols are quite standardized, and easy to document.

The things that are problematic are often everything else.

Here I’ll try to divide “everything else” into some things you should cover to make your integration journey a joyride.

Motivation

What is the motivation for building this integration? You should ask what you have to gain from the integration, and also what your integration partner will gain.
Is this integration a mainstream case for the partner, or is this something new?

A highly motivated partner will prioritize you and your relationship. You will get a personal contact, who is invested in making the integration work. A partner with little to gain, will probably give low priority to a special case. You are at the risk of long response times, and that your support contact doesn’t know your case and won’t make sense of your questions.

Keep it simple

Is this the way we should integrate with this partner, or could the purpose perhaps be fulfilled in any other way?
As an example from Adlede:

vs.

The first one requires a setup that can handle tens of thousands of requests per second with sub-millisecond response times (because network latency eats most of the allotted 10 ms response times). This is state-of-the-art in the business, but is expensive for both parts in terms of data usage.
The other one requires a simple API call with updated sitelists when new content is analyzed, usually a couple of times per hour.

If one solution is more cumbersome (or expensive), are there other reasons for doing it? Like learning, showing off, making intellectual property, or just because it is fun?

Learn to know your integration partner

How should this integration work from a user perspective? Learn how to use the platform, what are known best practices. Is it possible to do what we aim for? You should involve both your development team and your business lead to find out potential pitfalls ahead of a decision.
In the Adlede case, we have had a lot of trouble because we underestimated the complexity of a partner platform, and found a lot of special cases when working with customers using different setups and other partners.
Is your integration a special case for the partner? As a special case it is important to keep track of communication, preferably with a lot of note-taking, and writing summaries of email threads so you (or your colleagues) can find out who promised what a year later. Maybe your solution will be undocumented, and the partners support organization will have trouble answering your questions.

The ad business loves optimizations (for example “Maximize reach” or “Max clicks”) - but usually details about them are not disclosed. The optimizations are often made to work on user data, in combination with information collected about clicks and ad costs for the domains. They can collide with a contextual solution that only targets specific URLs. Such “black boxes” of secrets have given us some headaches and confusing troubleshooting until we have got a good enough understanding of them. Would have been nice to know about them in advance.

One thing that everyone wants in the ad business is reporting about how a campaign delivers, and in our case how our segments perform. That may sound obvious to get that kind of data, but experience says otherwise. A continuous feedback on url level can be used for optimizations in close to real time. The usefulness of aggregated reports sent at the end of the month is much smaller, but is at least something. Worst case, you have to trust your client using your data to send you reports of their usage. This is good to know before you plan on having short feedback loops in your system.

At this point, you should be able to make an informed decision whether you should make this integration or not.

Before you start coding

Make sure you have a technical contact at your integration partner that knows their system and knows their side of your integration. The general user support may not have enough technical knowledge of their own system, or know how your integration is built at their end. If that’s the case, you are up for a lot of frustration, and seemingly asking the same questions over and over again.

Make sure you have access to technical documentation, enough to understand not only your API, but also get an overview of the whole platform.
Subscribe to email lists regarding system updates, releases and issues, and make sure that your development team gets these emails.

Use your imagination and search for undocumented (or hidden) limitations or constraints you aren’t aware of that can affect your integration. For example, it is better to find out about a rate-limiting before the service goes down, or that you regularly need to update your API key. The frustration from the developers will be extreme if the behaviour of the API suddenly changes, making your calls fail—and you haven’t got any notice about it.

Before going live

Often a “Test client” is lined up to test the integration as soon as possible and show that the business model works. The “Test client” usually comes with a deadline, a budget to spend, and targets to reach. This can create a lot of stress for your developers to onboard an external partner before they have ironed out the worst wrinkles and signed off that the system is “good enough” to use.

Before going live, you should have had time to figure out how you use the platform to do what you want, and preferably have a version 0 of a “Best practices”-document and a troubleshooting flowchart at hand.

To conclude

Integrations are all about communication and information—however, the hardest part is the human part of the communication, to make sure that both the people building the integration and the users of it have enough information to be able to make it fly!

Mona.png

By Mona Forsman, Head of Research and Development @ Adlede

Read more