Getting Started with the JavaScript API
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.
The Monetate JavaScript API implementation consists of four components:
- Monetate tag: The Monetate tag is a block of JavaScript code that you place within your site's global <head> element. The tag gives Monetate the ability to access a page's DOM to drive site changes and the ability to track and target visitors based on contextual in-session data points (for example, IP address, device type, marketing referral channel).
- Monetate JavaScript API: The Monetate JavaScript API consists of JavaScript method calls that are easy to implement and maintain. The API methods allow you to use Monetate to track and target visitors based on onsite behavior (for example, products browsed, products purchased, amount in cart), to capture conversions, and to better understand the structure of your site.
- Third-party analytics: When you implement third-party analytics, Monetate can pass all event-based activity to your Web analytics provider so that your analytics team can understand which visitors have seen which experiences in the Monetate platform.
- Product catalog: You must upload a product catalog to use Monetate's merchandising capabilities and to target products in the WHO settings of a Web experience by any hierarchies, product type, or product attributes specified within the catalog. Although uploading a product catalog isn't required for day 1 unless you're using Monetate's recommendations and badging features, nevertheless you should upload one as soon as is feasible.
The time it takes to add the Monetate tag and the required method calls that are important to your business can vary. The number of method calls you must add, your intended use of Monetate, and the skill set of the person completing these tasks can all impact how long it takes to complete the process. For more information about who should complete the various steps of this process and what to expect, refer to Implementation User Roles.
There are two steps to pass site data to Monetate. The first is to add the Monetate tag to your site, and the second is to add method calls to your site to pass visitor data to Monetate.
Adding the Monetate tag to your site allows you to develop actions with Action Builder, create and track events with Event Builder, and launch experiences.
Method calls allow Monetate to build a page map to better understand your site visitors. It also allows you to use Monetate's behavior-based targeting and to unlock additional metrics in Experience Results beyond what's available out of the box.
For example, if you want to build an experience that considers what products specific customer segments buy or if you want to track KPIs such as conversion rate and abandoned cart rate, you must use the method calls in the Monetate JavaScript API. These calls also allow you to track conversions from your site's shopping cart, track product details, or set page types to take full advantage of Monetate.
Monetate also supports various eCommerce connectors.
The Monetate JavaScript API allows you to send customer interactions with your site to Monetate (for example, adding items to the cart, making a purchase, and more). This enables you to instruct Monetate about your site structure and relevant interactions of any visitor, including the following:
- Assign page types based on page information and the anatomy of the page, and then use this information to tie actions to page types, which are groups of specific pages (for example, add an action condition in Monetate so that an action only appears on product search pages)
- Track visitor behaviors, including pages visited, categories searched, and products selected so that you can, for example, create an experience to segment any visitors who previously viewed men's shirts in the last 30 days
- Track how a visitor moves through the funnel and measure different conversions (for example, view reporting dashboards in Monetate that may state, "For this experience, Split A shows a 10% uplift in conversion vs. the control")
You can add most Monetate JavaScript API method calls directly to your site or via a tag management system (TMS) anywhere within a page template.
You cannot, however, initialize the monetateQ and trackData methods using either of the aforementioned approaches.
Implement monetateQ at the top of the page template just below the Monetate tag in the <head> element of your site to ensure the object is initialized when calling other API methods.
Implement trackData at the bottom of the page template after all the content has been loaded.
The sample code in this screenshot shows monetateQ inserted just below the code for the synchronous version of the Monetate tag and trackData inserted at the very bottom of the <body> element.
Monetate has an array of features that are available to you as you pass more data from your site. This table provides some context for what information the platform needs to accomplish certain things on your site.
I Want to... | What Do I Need to Implement? |
|---|---|
Display banners on all pages or by URL | Monetate tag |
Display lightboxes on all pages or by URL | Monetate tag |
Execute HTML added or modified on all pages or by URL | Monetate tag |
Execute CSS on all pages or by URL | Monetate tag |
Display an experience on certain pages with a selector | Monetate tag |
Display an experience on certain pages with information in a cookie | Monetate tag |
Display an experience on certain pages with information in a JavaScript variable | Monetate tag |
Display an experience on certain pages that contain text or a number on a page | Monetate tag |
Display an action specific to the customer's page of entry | Monetate tag |
Display an image action including dynamic geographic text or dynamic weather text | Monetate tag |
Target pages with a certain HTML element, certain text, or numbers within a specified HTML element | Monetate tag |
Target pages with a specific JavaScript variable or pages with specified text or number contained within a specific JavaScript variable | Monetate tag |
Target pages with a specific cookie or pages with specified text or number contained within a specific cookie | Monetate tag |
Target technographics | Monetate tag |
Target US demographics | Monetate tag |
Target US weather | Monetate tag |
Target US locations | Monetate tag |
Target visitor landing page (except custom variable and products out of stock), visitor time on site, visitor page views, last visit, number of sessions in past days, days since last visit, bounce rate, page views, and time on site | Monetate tag |
Measure interactions, impressions, and URL goals | Monetate tag |
Display an action specific to products shown on page | IDs of products on a page |
Target products viewed this visit, last visit, and products ever viewed | Product view events (addProducts) |
Display product badges on select items | Product recommendations and product IDs on multi-product pages |
Display product badges on select items | Product recommendations and product detail information on single-product pages |
Display a recommendations slider by product type | |
Display specific products or the newest items added | |
Display a recommendations slider with similar items, most frequently viewed items, recently viewed items, or items viewed after viewing a certain item | Product recommendations, a product catalog, and product view events (addProducts) |
Display a recommendations slider with items purchased in addition to another item (purchased and also purchased) or items viewed in addition to another item (viewed and also viewed) | Product recommendations, a product catalog, product view events (addProducts), and purchase information (addPurchaseRows) |
Target categories or brands viewed during the current visit, last visit, or ever | Product recommendations, a product catalog, and product view events (addProducts) |
Target out-of-stock products | Product recommendations, a product catalog, and product view events (addProducts) |
Display an action specific to a customer's cart value or an image action including total merchandise in cart | Cart information (addCartRows) |
Target products in cart or abandoned cart, amount in cart or abandoned cart, quantity in cart or abandoned cart | Cart information (addCartRows) |
Measure add to cart rate and cart abandonment | Cart information (addCartRows) |
Target categories or brands in the cart or abandoned cart | Product recommendations, a product catalog, and cart information (addCartRows) |
Target average order size, last order size, days since last purchase, product purchased, last product purchased, product purchased in last days, purchased any product, purchase frequency, purchases made since a date, purchases made in a past number of days | Purchase information (addPurchaseRows) |
Target average order size, last order size, days since last conversion, product purchased, last product purchased, product purchased in last days, purchased any product, purchase frequency, purchases made since a date, purchases made in a past number of days | Conversion information (addConversionRows) |
Measure lift in average order value, revenue per session, conversions, and new customer acquisitions | Purchase information (addPurchaseRows) |
Measure lift in average order value, revenue per session, conversions, and new customer acquisitions | Conversion information (addConversionRows) |
Display a recommendations slider by top-selling purchase count or top-selling revenue | Product recommendations, a product catalog, purchase information (addPurchaseRows), and conversion information (addConversionRows) |
Display a recommendations slider by products purchased in addition to another purchased product | Product recommendations, a product catalog, product view events (addProducts), purchase information (addPurchaseRows), and conversion information (addConversionRows) |
Target categories purchased, categories last purchased, brands purchased, or brands last purchased | Product recommendations, a product catalog, purchase information (addPurchaseRows), and conversion information (addConversionRows) |
Display an action on certain pages | Page type (setPageType) |
Display an action on certain pages | Page category (addCategories) |
Display an action specific to certain navigation breadcrumbs on the page | Breadcrumbs (addBreadcrumbs) |
Display an image action that includes dynamic text related to nearest store locations | |
Display an image action that includes other dynamic text | Custom variable (setCustomVariables) |
Target customers who match a custom variable | Custom variable (setCustomVariables) |
Target page type | Page type (setPageType) |
Target customers included or excluded from a dataset | Datasets and an on-site ID |
Measure more complex custom milestones | Custom event key (trackEvent) |
Use this worksheet to keep track of your progress while you implement Monetate on your site.
Hold planning meeting with all stakeholders
Install Monetate development tag to your development environment
Development of Monetate JavaScript API in development environment
Quality assurance check of Monetate JavaScript API in the development environment
Install Monetate production tag to your production environment
Deploy Monetate JavaScript API to your production environment
Quality assurance check of Monetate JavaScript API in the production environment
Enable Stealth Mode
Complete data alignment check
It's important to plan your Monetate JavaScript API deployment with all the team members who'll be involved in using Monetate in your organization. When all the stakeholders get together during the planning stages, you can set clear goals and expectations of what the business user can do within the Monetate platform.
Monetate recommends the following internal team members for planning your implementation:
- Business owner
- Project manager
- Engineer(s)
- QA personnel
The recommended baseline JavaScript API deployment includes the method calls that unlock many the platform's capabilities. See What Do You Want to Do on Your Site? for a complete listing of what features the API unlocks in the platform and how you can leverage them for experiences.
The first step to tracking your site data is putting the right person in charge of completing it. Typically, this person should be a software engineer, a back-end developer, or someone who has experience with JavaScript who can tag your site with Google Tag Manager or similar tagging systems.
Ultimately, the person who completes the process must possess these qualifications:
- Have the necessary access to modify site templates
- Be able to request page-specific data from your server (for example, a list of product IDs shown on the current page)
- Have enough familiarity with JavaScript to make API calls
The time required to complete the implementation depends on the technical complexity of your site, the number of different page types/templates, the complexity of the data you want to report, and how easy it is to query your site's back end for that information.
As a rule of thumb, an engineer familiar with your site should need about 10 to 12 hours of undivided attention to complete the necessary development for the baseline Monetate JavaScript API.
The next step in the process involves performing QA testing. It should be performed by someone who has experience similar to the person who added the method calls or by a QA professional or a marketer who is very familiar with your site. Most importantly, QA testing should be completed by someone other than the person who added the method calls to your site.
The key to successful QA testing of your site is to check that all templates and page types that should pass data to Monetate are doing so correctly.
Ultimately, the person who completes QA testing must do the following:
- Complete a conversion on your site, if that's important to your business
The time required to complete QA testing depends on the technical complexity of your site, the number of different page types/templates, the complexity of the data you want to report, and how easy it is to query your site's back end for that information.
As a rule of thumb, a person familiar with your site should need about 4 to 6 hours of undivided attention to complete QA testing.
After you complete QA testing your site's Monetate JavaScript API in your development environment, you can move the API code to production.
Ultimately, the person who completes the deployment to production must meet these qualifications:
- Have the necessary access to modify site templates
- Be able to deploy tags to your site via the tag management system