K Khan
Jun 22, 2021
  1426
(4 votes)

ODP handy reference guide - Web SDK

A quick reference guide, developers might need before starting a new ODP/Zaius implementation based on https://docs.developers.zaius.com/

It will be worthy to watch https://www.david-tec.com/2021/05/video-adding-optimizely-data-platform-to-optimizely-commerce-cloud/

Authentication

ODP/Zaius provides two forms of authentication:

  • Public (Tracker ID) - is used for most API calls that send data
  • Private - is used for querying data

Keys are scoped at the account level. When you revoke a private API key, your existing key is available for 12 hours as a grace period. Public API Key and Tracker ID are synonymous.

Batch Requests

Bulk data push should be done in batch, every request can include up to 500 distinct objects. As an example, at 500 customers per request with 10 requests per second as a rate limit, you can process 5,000 customer updates per second. For higher rate limits contact support.

Consent

Consent may impact attempts to send marketing campaigns to the identifier. If noted as opted-out, certain marketing services or channels may skip the identifier, even when qualified for the campaign. Customers who have opted out cannot receive marketing messages. Only transactional messages will be received by these customers.

Example: 

zaius.consent({  consent: true,  identifier_field_name: 'email',  identifier_value: 'tyler@zaius.com',  update_reason: '',  update_ts: 123456789,  event_data: {}  });

Messaging Lists

Group customers for the purposes of tracking their communication preferences.

Customers/Profiles

To Create/Update/View Customer’s profile. Cookie with name ‘vuid’ contains the reference to profile id.

Anonymize - will reset the cookie identifier associated with the browser. Use this when a user logs out or on shared devices between form submissions that include identifiers.

Example:

zaius.customer({
    email: "johnny.zaius@zaius.com"
  },{
    first_name: "Johnny",
    last_name: "Zaius",
    gender: "M"
  });

Events

Customer behaviors are tracked as events. Events are composed of a Type(a categorical name associated with the event), Action(activity a user did within that event type), and additional metadata via fields on the event,  at minimum, events require an event type and an identifier to associate the event with a customer. There are two types of events, custom, and standard,

Custom event:

Example:

zaius.event("your_event_type_here", { 
    action: "your_event_action_here",
    example_custom_field: "example_value"
});

Standard events:

These are pre-defined event type/action and expected by Zaius to be accompanied with certain fields. The usage of these events makes the usage of Zaius simpler for common use cases. Zaius does not recommend or formally support Order events via the Web SDK to ensure that ad blockers do not block the purchase event. Zaius only supports sending Order refunds, returns & cancellations via API or CSV to ensure that ad blockers do not block these critical events. https://docs.developers.zaius.com/api/

Event TYPE Activity Example
https://docs.developers.zaius.com/web-sdk/events/account
account login
zaius.event("account", { action: "login" });
logout
zaius.event("account", { action: "logout" });
register
zaius.event("account", { action: "register" });
update
zaius.event("account", { action: "update" });
Anonymize will reset the cookie identifier associated with the browser. Use this when a user logs out or on shared devices between form submissions that include identifiers.
anonymise
zaius.anonymize();
Zaius will automatically parse the appropriate page path information.
pageview
zaius.event("pageview");
https://docs.developers.zaius.com/web-sdk/events/navigation
navigation search
zaius.event("navigation", { 
    action: "search", 
    search_term:"cameras, vcr",
    category: "electronics > consumer"
});
sort
zaius.event("navigation", { 
    action: "sort"
});
filter
zaius.event("navigation", { 
    action: "filter"
});
https://docs.developers.zaius.com/web-sdk/customers/consent
consent opt-in
zaius.consent({
  consent: true,
  identifier_field_name: 'email',
  identifier_value: 'tyler@zaius.com',
  update_reason: '',
  update_ts: 123456789,
  event_data: {}
  });
opt-out

https://docs.developers.zaius.com/web-sdk/events/products

product_id is required on all events with an event type of product

product detail
zaius.event("product", { action: "detail", product_id: "product-2143" });
add_to_cart
zaius.event("product", { action: "add_to_cart", product_id: "product-2143" });
remove_from_cart
zaius.event("product", { action: "remove_from_cart", product_id: "product-2143" });
add_to_wishlist
zaius.event("product", { action: "add_to_wishlist", product_id: "product-2143" });
remove_from_wishlist
zaius.event("product", { action: "remove_from_wishlist", product_id: "product-2143" });
https://docs.developers.zaius.com/web-sdk/events/ads
advertisement impression
zaius.event("advertisement", { action: "impression" });
click
zaius.event("advertisement", { action: "click" });

Messaging Lists allow you to group customers for the purposes of tracking their communication preferences. For example, allowing customers to subscribe to your company newsletter or for holiday news. 

Zaius does not require customers to be subscribed to a List to receive emails.

subscribe
// subscribe johnny@zaius.com to newsletter list
zaius.subscribe({list_id: 'newsletter', email: 'johnny@zaius.com'});

// unsubscribe johnny@zaius.com from newsletter list
zaius.unsubscribe({list_id: 'newsletter', email: 'johnny@zaius.com'});

// subscribe johnny@zaius.com to three lists at once
zaius.subscribe({
  list_id: ["newsletter", "promotion", "product_update"], 
  email: "johnny@zaius.com"
});

// unsubscribe johnny@zaius.com from multiple lists at once
zaius.unsubscribe({
  list_id: ["newsletter", "product_update"], 
  email: "johnny@zaius.com"
});

zaius.subscribe({
  // subscribe Johnny to all lists
  
  list_id: ["newsletter", "promotion", "product_update"],
  email: "johnny@zaius.com",
  
  // update Johnny's record to include his full name
  first_name: "Johnny",
  last_name: "Zaius",
  
  // store information on the subscribe events
  event_custom_field: "my custom value",
  custom_number_field: 123
  
});

// zaius.unsubscribe also fully supports this syntax.
Jun 22, 2021

Comments

David Knipe
David Knipe Jun 22, 2021 01:08 PM

Thanks for sharing, all useful information! I have updated https://www.david-tec.com/2021/05/adding-optimizely-data-platform-to-optimizely-commerce-cloud/ to reference this guide :)

K Khan
K Khan Jun 23, 2021 05:43 PM

Glad you liked, and thanks for giving this post space there :)

Johnny Mullaney
Johnny Mullaney Feb 9, 2022 03:09 PM

Thanks for writing this guide Khurran, very useful!

If a customer logs in, do you know if it is best practice to push both a login event and a customer event:

zaius.event("account", { action: "login" });
zaius.customer({
    email: "johnny.zaius@zaius.com"
  },{
    first_name: "Johnny",
    last_name: "Zaius",
    gender: "M"
  });

Similarly if a customer identifies their email through a guest checkout journey, i assume that we push a customer event such as the following to identify the session

zaius.customer({
    email: "johnny.zaius@zaius.com"
  });

Thanks in advance :)

Brian Taylor
Brian Taylor Feb 9, 2022 05:55 PM

Only the login event unless there's a chance that you just captured something new about the customer. You only need to fire customer events to ask ODP to retain something new you've discovered about the customer and whatever you send will be merged with what ODP already knows.

Johnny Mullaney
Johnny Mullaney Feb 10, 2022 11:28 AM

Great, thanks Brian!

Please login to comment.
Latest blogs
Plug-in manager is back in CMS 12

Plug-in manager is back in the UI, what is it and how can i use it?

Luc Gosso (MVP) | Oct 6, 2022 | Syndicated blog

Display Child Pages in Content Delivery API Response

The below example will implement an instance of IContentConverterProvider to customise the serialisation of PageData and output child pages in the...

Minesh Shah (Netcel) | Oct 4, 2022

Bring the Report Center back in Optimizely CMS 12

The Report Center has been a part of Optimizely CMS since its first debut in version 5R2 in 2008, but in CMS 12, it's removed! Don't despair! Make...

Tomas Hensrud Gulla | Oct 4, 2022 | Syndicated blog

Customizing Property Lists in Optimizely CMS

Generic property lists is a cool editorial feature that has gained a lot of popularity - in spite of still being unsupported (officially). But if y...

Allan Thraen | Oct 2, 2022 | Syndicated blog

Optimizely names Luminary Senior Developer, Ynze Nunnink, OMVP

Luminary Senior Developer and Optimizely Lead, Ynze Nunnink has secured the coveted position of Optimizely MVP. Earning a Platinum badge for his...

Ynze | Oct 2, 2022 | Syndicated blog

Content Delivery API – The Case of the Duplicate API Refresh Token

Creating a custom refresh provider to resolve the issues with duplicate tokens in the DXC The post Content Delivery API – The Case of the Duplicate...

David Lewis | Sep 29, 2022 | Syndicated blog