Types of Implementations
Monetate offers three primary deployment options: Monetate JavaScript API, Engine API, and Monetate SDK. A hybrid implementation of the Monetate JavaScript API and Engine API is possible.
The Monetate JavaScript API allows you to pass page-level data to the Monetate platform. It follows common eCommerce patterns and is straightforward for experienced front-end developers. Each method call is categorized by the type of page for which it is intended or most often used.
In a traditional Monetate tag–based integration, Monetate is running in the browser and can directly manipulate your site by inserting, editing, or removing content via reusable actions. Monetate can additionally leverage DOM elements (cookies, JavaScript variables, HTML elements) to target and track site-specific segments and events. By implementing the Monetate JavaScript API methods, Monetate additionally collects (and targets against) behavioral data such as products that have been viewed, carted, and purchased.
The Engine API is a RESTful API that serves as a direct entry point to Monetate's decision engine and allows clients to use it in any channel: Web (server-side or within the browser), mobile applications, SPA frameworks, and nontraditional implementations such as in-store displays or SMS/text messaging.
When using the Engine API, you must pass all page- and visitor-level data to Monetate within the request body:
- IP address and latitude and longitude coordinates for geographical targeting
- User agent for technographic targeting
- Additional context such as URL, page type, product IDs, and SKUs as they're viewed, carted, or purchased, as necessary
Monetate doesn't directly drive changes to the requesting application. Instead, the Engine API response contains JSON-formatted data (often configured in advance by the end user) that the requesting application then reacts to. See Available Action Types in the Monetate Knowledge Base for more information on the available action templates for Engine API experiences.
The Engine API allows three things to be done with a single call:
- Send contextual information about the current visitor/page.
- Retrieve actions that are supposed to fire in the current context. These actions can be part of any Omnichannel experience in Monetate and can be a mix of personalized content and tests to be activated.
- Send events/metrics to Monetate to measure success.
Bundling all these capabilities into a single endpoint allows all data to be received via a single call and reduces latency when transmitting to Monetate.
Every time something is sent to the Engine API, it's similar to a retrack. If a decision request is sent with a page view, it's similar to the track call (for example, selecting a color on a product details page).
A decision request can be sent without a page view (for example, just the color SKU), which only counts as a single page view.
Monetate recommends taking a "personalization-aware design" approach, where UI components check for personalization decisions prior to rendering, or render a loading indicator while awaiting the personalization decision. This personalization decision may involve replacing or otherwise overriding the components' default content, so it is advised to not display default content until the personalization decision has been received. If the application is structured in such a way that each UI component or structure can be checked for personalization overrides before rendering, code pushes simply to run experiences can be avoided.
- Identify default components and structures
- Identify which components and structures within the app can be personalized
- Create a store for personalization decisions that may override default components and structures
- Upon render, check the decision store for personalized components
Keep in mind the following points if you're considering implementing Engine API in a mobile app:
- The importance of persisting a monetateId (or deviceId) remains.
- A request must be made any time the app user views a product (monetate:context:ProductDetailView), manages their cart contents (monetate:context:Cart) or makes a purchase (monetate:context:Purchase). This enables Monetate to track the behavior for reporting/analytics as well as for recommendation algorithms (as applicable).
To test against specific device(s), include a testing custom variable by default:
When used within a website, the Engine API should be implemented with the traditional Monetate tag-based approach in a hybrid implementation. In this way the Monetate JavaScript API can be relied on for all core reporting and analytics. Depending on your team's governance model, the Engine API can be used for some or all testing and personalization decisioning.
So long as the monetateID (or deviceId) is persistent across both the Engine API and Monetate JavaScript API deployments in a hybrid implementation, Monetate ensures that sessions aren't counted twice because it reconciles the persistent ID into a single session. Page view metrics are only recorded by the Monetate JavaScript API to prevent double counting.
With hybrid implementations, the Engine API requests can be made entirely server-side, entirely within the browser, or some combination of the two. The exact implementation is dependent on your familiarity with your site architecture and how you want to communicate with Monetate.
Regardless of whether Engine API requests are made server-side or within the browser, the most important thing is to establish a governance model which controls when and where you do or do not use Monetate tag–based experiences (where actions run and can directly manipulate the DOM) or Omnichannel experiences (where the Engine API returns a decision and your site reacts to that decision to render the personalized content).
Keep in mind the following points if you're considering a hybrid implementation:
- Monetate tag–based experiences allow the continued use of marketer-friendly tools (Action Builder, Target Builder, WYSIWYG editors, etc.) to directly manipulate the site with little to no knowledge of front-end Web development code and with little to no lead time.
- Omnichannel experiences require more development resources and time to ensure the correct context is being passed and the correct logic is being applied to render the personalized content.
- Monetate tag-based experiences can sometimes experience flicker as the site and Monetate are "competing" to render the personalized content.
- Omnichannel experiences, when implemented properly, can completely eliminate the occurrence of flicker because of the ability to control what renders on the page and when.
Best practices for a hybrid implementation are as follows:
- Implement the Monetate tag and API methods for reporting and analytics collection.
- Implement Engine API requests when desired or necessary for decision requests and event recording (such as API events, managed impressions, recommendation item impressions, recommendation item clicks). Depending on the site architecture, Engine API requests may be made server-side, within the browser, or some combination of the two.
- Establish an internal governance model for when or where to deploy experiences, such as in these examples:
- Use the Monetate JavaScript API solely for reporting and analytics and Engine API for all experiences.
- Use Engine API for high-impact, above-the-fold experiences, and use the Monetate JavaScript API for lower impact experiences.
- Define clear use cases for the agility of the Monetate JavaScript API versus the performance of Engine API.
- If you're using an SPA framework, the same logic can be applied with the following additional considerations:
- The Monetate JavaScript API implementation requires retracks whenever the state of the page changes so that Monetate can re-evaluate for any Monetate tag–driven experiences and properly collect analytics.
- Engine API requests should be made from within the browser.
Single-page applications, such as those built with React or Vue, can present unique challenges to how the Monetate JavaScript API implementation drives testing and personalization changes. While these challenges aren't insurmountable with just the Monetate tag–based approach, more clients pursue a hybrid implementation within their SPA.
When using a hybrid implementation within an SPA, the Engine API may be called from the server on initial app load but from within the browser as the customer navigates the app or whenever the state changes.
SPA frameworks can also use a front-end method of implementation. In this method, the Monetate tag remains, and the Engine API is used—but from the front end.
For example, in an SPA for which the front-end stack is based on React, some out-of-the-box actions operating on the DOM confuse React (or other JavaScript frameworks), and then block it from rendering subsequent changes. By using the Engine API, hooked into some data mutation and template-change functions, actions can instead change front-end templates or component configurations. The SPA, therefore, still works as designed while allowing clients to create A/B tests and personalization experiences.
Here are some of the benefits of using an SPA front-end implementation:
- There's no need to change back-end services.
- Data is still collected with the Monetate tag, so there's no need to re-implement data collection.
Here are some of the drawbacks to using an SPA front-end implementation:
The Monetate SDK is a library of objects and methods that allow you to easily utilize the capabilities of the Engine API. Using methods that simplify the API calls, you can create and run an experience quickly and with minimal effort. The SDK can be used for any channel, including Web, mobile apps, and SPAs.
The Monetate SDK simplifies the API calls by acting as a translation layer to the Monetate decision engine. The SDK provides easy-to-use methods that send event data directly to the decision engine and receive the experience to serve.