Overview of the Kameleoon APIs
Context
The Kameleoon platform provides several APIs that our customers can use for various purposes. For instance, the APIs allow to write front-end A/B experiments without any flickering, better integration within your digital ecosystem (pulling data from Kameleoon as well as sending data to Kameleoon), or to automate certain tasks. It's very important for us to provide your technical teams with advanced, fully documented APIs so that you can use the Kameleoon platform to its most complete extent. Customizing and tweaking our software is also totally possible thanks to these APIs.
We regrouped our various APIs into three main groups: the Activation API (JavaScript API), the Automation API (REST API), and the Data API (REST API). The goal of this article is to provide a very high-level overview of these three APIs, so that a developer tasked with a specific development can quickly identify which API is needed and refer to its documentation. It also serves as a good basis to demonstrate the openness of our platform, its technical features and the many ways it can be expanded and connected to other systems.
The Activation API
The Activation API is a JavaScript API provided by the Kameleoon application file installed on your website. You can call the methods of this API directly via JavaScript code. You can also read useful information from a variety of data structures available via this API. For instance, we provide geolocation and weather data of the current visitor, as well as the KCS (Kameleoon Conversion Score), our real-time, customer-centric, machine-learning powered score (note that the KCS is only available if you activate our A.I. Personalization module).
This API serves several purposes:
provide methods to implement front-end based A/B testing variations that won't result in any flickering effect. It is extremely important to use these methods in order to correctly operate the Kameleoon platform and leverage our Anti-Flickering technology. Any Front-End developer working with Kameleoon should be familiar with them.
provide tracking methods to send data to Kameleoon (such as conversion data, or visitor / customer characteristics such as age, sex...). The methods available here as similar to the ones generally provided by an Analytics solution such as Google Analytics. You can call these methods directly via embedded JavaScript code on your HTML pages, or via code operated from a Tag Manager such as GTM (Google Tag Manager).
provide a set of methods to manage the catalog of products on your website. For instance, it should be used to register a product view or purchase, add a product to the cart, obtain a set of automatic product recommendations, or obtain statistics about a given product (how many times it was bought or viewed in the last hour or day).
provide useful information gathered by Kameleoon. These data are updated in real-time. For instance, the number of page views for a visitor is obviously incremented each time a new page is loaded. Note that our data layer is stored and is available for all previous visits of this particular visitor. You can for example know how long a visitor stayed on your website during his first visit even if he's currently at his 5th visit.
provide entry points to override the standard behavior of our software. For instance, normally when a visitor is triggered into an A/B experiment for the first time, the association of this visitor to a variation is done randomly. With the API you can override this association and register the visitor into a given variation. This is particularly useful when implementing server-side testing via our SDKs, but with front-end reporting.
In short, refer to this API when you want to implement experiments or personalizations, track data using Kameleoon, retrieve Kameleoon-gathered data for your own use, interact with your product catalog, or customize and extend any aspect of Kameleoon performed on the front-end / browser.
Note that as this API is fully JavaScript based, there is no need to worry about the scalability of its usage. Almost all methods (except a few that transparently require a server call, such as those dealing with the product catalog) return immediately and perform their action synchronously. No authentication is required for this API. Basic browser architecture and security ensures that visitors can only access their own data (stored in the Local Storage), not the data of other visitors.
The Activation API is fully documented here. There is also a separate article for custom JavaScript Kameleoon Events.
The Automation API
The Automation API is a REST API that allows you to programmatically trigger and perform almost every action that is possible via our standard (web-based) user interfaces. This means that you can write your own software, able to interact with our platform, harnessing all of its features and capabilities. As an example, some of our customers took advantage of this API to implement bridges between Kameleoon and their own Git repositories, so that Kameleoon variation code may be managed directly on their usual version control system. You could also design your own dashboard and fill it with experiment results directly obtained from Kameleoon. Building custom systems operating or interfacing with Kameleoon is easy thanks to this API.
This API is a REST compliant API, so you can call it with any REST capable framework in any language (Java, C#, NodeJS, Python, etc). We conform to REST conventions and any developer familiar with them should feel at ease here. However, this API is not intended to be used extensively. By this we mean it's intended to be called a dozen of times per minute and per customer / user account on our systems. It's not scalable to millions of calls per minute, so should not be called for every visitor on your website (if you need this, see the Data API instead for more information).
Note that the Automation API uses the OAuth 2.0 authorization framework.
The Automation API is fully documented here.
The Data API
The Data API is a REST API that allows to retrieve or write data stored on remote servers, not locally on the visitor's browser. So contrary to the Activation API where data is available directly and instantly on the browser side, this API is intended for communication with external data sources / remote servers / DMPs. It is however scalable to millions of calls per minute (unlike the Automation API), so calling this API for every visitor is perfectly possible.
For instance, this API is used for Cross-Device History Reconciliation, a powerful Kameleoon feature that allows the complete history of actions for a given Unique Visitor to be synchronized automatically accross all his devices. If one of your visitors browses your website twice using his smartphone, then comes again later on his desktop computer, we'll correctly report this as his third visit in the Activation API data layer. Underneath, a call to our Data API was made to ensure the synchronization of data via our servers.
Another good example of usage would be to register "late transactions" which cannot be sent directly on the web-platform via the usual Activation API. If your business sells travel packages, and the final transaction / confirmation is not achieved on your website, but later in person, in a physical outlet for example, you can use this API to register those transactions, which would be impossible with a web / JS based API.
The Data API is a REST compliant API, so you can call it with any REST capable framework in any language (Java, C#, NodeJS, Python, etc). We conform to REST conventions and any developer familiar with them should feel at ease here.
The Data API is not yet documented. We expect the documentation to be ready for the end of 2020.