This document explains how to integrate Scope Javascript libraty (plytix.js) in your e-commerce store and start collecting data. Thanks to Scope you'll be able to see how users interact with the products present on your website.

 

Set up your Scope account

The first step to using Scope with your e-commerce platform is set up a Plytix account. If you don't have an account yet, please register here. If you already have a Plytix account, you can get started with Scope from your in-app navigation menu.

 

Get your API credentials

To integrate Scope in your e-commerce system you need to get the API credentials for your account. The API account ID is a unique key used for validation when your site is using the Plytix API. E.g., for all the data received in Plytix servers, those actions sent along with your API ID are attached to your account.

You can find your API credentials in your account administration page.

 

Track data

Add plytix.js to your website

The last step in the integration of Plytix in your e-commerce store is to import the plytix.js library. plytix.js has no Javascript dependencies.

You need to import the library and then instantiate the _pl object so it can be used. You get all that done by pasting this code just before the tag




_pl function

The _pl function provides you access to all the functionalities available in the plytix.js library. The above snippet initializes it as a queue. All arguments sent to it will be stored until plytix.js load is finished. Once plytix is loaded, _pl is redefined to a function and it executes all calls stored in the queue.

Life cycle

The natural life cycle of the plytix.js in a website using Plytix Analytics is as follows:

  1. Initialize and set API credentials.
  2. Send any action stored in _pl before it was loaded.
  3. On-demand data tracking.

 

Tracking product impressions and user actions

Once the _pl object has been instantiated, you can use it to track user actions -- e.g. when a user adds a product to the cart.

When working with plytix.js you handle different types of objects and operations, each one having certain data. Here's a list of them:

  • Product impression: Used to declare a product has been listed together with others (category view, related products, etc.)
  • Product actions: Different actions that can be performed on one or more products (add to cart, view product details...)
  • Product information: Product details to be sent along with an action. Products are declared just before an action. Products declared without a following action are irrelevant data wise.

Product impressions

Used to notify a product has been viewed, usually along with other products. If you want to notify a product details page has been accesed, use the detail product action instead.

Typical usages are products being listed in a home page, category page, related or cross-sell products, etc.

 

Key Type Required Description
id text Yes* Unique product identifier (ideally product's SKU or your shop system's product ID) *Either this or product name is required
name text Yes* The product's name *Either this or id is required
gtin text No The product's GTIN code
list text No Where the product is being listed (e.g. Home Page)
brand text No Product's brand name
category text No The category to which the product was assigned to, any of Google's product categories using / for hierarchy separator. (e.g. Media/Books)
variant text No Product's variant (e.g. Extended edition)
position integer No The position in which the product has been listed
price currency No The price of the product

 

Product actions

Here's a list of the different actions that can be delared using plytix.js library:

Action Description
click A product link has been clicked (e.g. inside a list or as part of a multiple selection)
detail A product'd detail page has been accesed.
add One or several products are added to the shopping cart.
remove One or several products are removed from the shopping cart.
checkout One or several products get to the checkout stage.
purchase One or several products have been sold

 

Product information

You can use product information objects to send data about the products your users are performing actions on. The product information must be sent before the action, so the latter is bound to the right product or set of products.

Product information can include any of these values:

Key Type Required Description
id text Yes* Unique product identifier (ideally product's SKU or your shop system's product ID) *Either this or product name is required
name text Yes* The product's name *Either this or id is required
gtin text No The product's GTIN code
brand text No Product's brand name
category text No The category to which the product was assigned to, any of Google's product categories using / for hierarchy separator. (e.g. Media/Books)
variant text No Product's variant (e.g. Extended edition)
position integer No The position in which the product has been listed (in case it's in a list)
price currency No The price of the product (e.g.: 19.99)
quantity integer No The quantity of units of a given product

 

Sending data

The process of sending data differs betwen a product impression, which requires a single API call or product actions which requires at least 2 (1 per product involved, and another one for the action itself).

Product impressions

This code sends a product impression:


_pl('addImpression', {
    'id': 'SK1234-1',
    'name': 'My fancy best seller',
    'gtin': 'ABC-1234-5678',
    'category': 'Media/Books',
    'brand': 'My cool brand',
    'variant': 'Extended edition',
    'list': 'Featured products',
    'position': 3
});

 

Product actions

This code indicates that 2 different products have made it to the checkout page.

Notice we declare the products first and then we set the action.


_pl('addProduct', {
    'id': 'SK1234-1',
    'name': 'My fancy best seller',
    'gtin': 'ABC-1234-5678',
    'category': 'Media/Books',
    'brand': 'My cool brand',
    'variant': 'Extended edition',
    'price': 29.99,
    'quantity': 1
});
_pl('addProduct', {
    'id': 'SK1234-2',
    'name': 'My fancy best seller',
    'gtin': 'ABC-1234-5679',
    'category': 'Media/Books',
    'brand': 'My cool brand',
    'variant': 'Simple edition',
    'price': 19.99,
    'quantity': 2
});
_pl('setAction', 'checkout');