Web API v1¶

The Voyado Elevate 3 Web API makes it easy to integrate Elevate into a site by enabling both client and server side integration. It consists of two main components:

• A JavaScript library
• A RESTful API

The Web API also includes methods for GDPR data management for Voyado Elevate data.

Getting started¶

Supported browsers¶

The Web API is built to support major browsers such as Mozilla Firefox, Google Chrome, Safari, and Microsoft Internet Explorer (10 and newer).

Prerequirements¶

Voyado Cloud environment configuration is a part of the customer onboarding process. This configuration is performed by Voyado, but for it to be completed some information regarding origin host settings and selected client side payment strategy are needed from the customer. The customer must also verify that the connection requirements are met when using the RESTful API.

With this provided to Voyado the initial set-up for the Web API will be performed, and the following information is returned to the customer.

• A private key - used for visitor sign in and dynamic pages
• Cluster ID - used when requesting data from the Voyado Cloud
• Cluster credentials - used when importing data to Elevate 3
• Voyado Elevate apps and Manager access rights

The private key and cluster ID are also available in Credentials tab of the Integration app. If an alternative API base URL is to be used, this will be provided by Voyado.

When the cloud configuration is completed, customers can contact Voyado Support if there are any questions about the current security settings used for their Elevate cluster, or if the security settings must be changed.

Origin host¶

The origin host is part of the security settings for a cluster. It specifies what domain Ajax requests to the cluster is allowed to originate from.

The following information is needed from the customer to configure the origin host.

• Protocols (HTTP/HTTPS)
• Domains (subdomains)
• Ports (80, 443)

Client side payments¶

Client side payment strategy is part of the security settings for a cluster. There are three different strategies for handling payment notifications with the Elevate 3 Web API.

• Do not allow payment notifications - This strategy should be used when payment notifications are always sent server side. Recommended for production clusters.
• Allow limited payments - Ignore suspicious payments e.g. payment notification that seem to be machine generated.
• Allow all payment notifications - Most useful at an early stage of the integration.

Connection requirements¶

• TLS version 1.3 is recommended. Version 1.2 is supported.
• Server Name Indication (SNI) enabled.
• A CA certificate store that trusts Let's Encrypt root certificates. For more information, see Let's Encrypt Certificate Compatibility.
• HTTP/2 is recommended. Version 1.1 is also supported.

JavaScript library¶

The JavaScript library exposes methods to fetch panels and notify events as clicks, adding to carts, etc. It communicates via Ajax requests with an Elevate 3 Web API Service on the Voyado Cloud.

For more details of the JavaScript library, see the JavaScript library documentation pages.

RESTful API¶

The RESTful API handles the communication with the Voyado Elevate Cluster. Load balancing and failover are both handled automatically.

For more details of the RESTful API, see the RESTful API documentation pages.

Sessions and notifications¶

Sessions and notifications are used to keep track of information about visitor interaction that is sent to Elevate via the Web API. This information is used to enable personalisation and to improve recommendations and more.

For more details about Notifications, see the Sessions and notifications page.

Recommendations and best practice¶

• Always instantiate an esales object as a variable with a URL to a cluster and market that exists.
• A general rule of thumb is to never cache Elevate generated results. Static data such as descriptions and images can be cached.
• When notifying payments, the recommended notification method to use is Secure payment notification.