SDK Integration Guide for E-Commerce Websites

This documentation provides a detailed guide on integrating the GoPersonal SDK into an e-commerce website. The integration is essential for enabling personalized content and recommendations for your customers. This guide is particularly relevant if you are not using a supported platform like WooCommerce, Magento, Shopify, etc.

Important Concepts

  • Custom Integration Requirement: Integration with the GoPersonal SDK is required if your e-commerce platform is not directly supported.

  • Single Page Application (SPA) Consideration: Identify whether your site is a Single Page Application, as additional SPA-specific considerations apply.

Pre-requirements

Before beginning the integration process, ensure you have received a unique clientId for each environment (e.g., development, testing, and production). Each clientId is associated with one or more domains. You can configure these associations in the GoPersonal dashboard under Integrations.

Installation Steps

To enable personalization features across your website, follow these installation steps on every page where you wish personalization to occur. This process is akin to integrating Google Analytics, requiring you to insert a script within the <head> tags of your HTML pages.

  1. Script Installation: Replace REPLACE_ME_CLIENT_ID with your actual clientId in the script below and add it to the <head> section of your HTML pages.

    <script>
async function initializeGSSDK() {
    window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
        provider: 'Custom',
        context: { pageType: 'home' } // This context varies based on the page
    });
}
var gsSDKScript = document.createElement('script');
gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
gsSDKScript.onload = initializeGSSDK;
document.head.appendChild(gsSDKScript);
</script>

Context Configuration Examples

Depending on the type of page, the context parameter in the script must be adjusted. Here are examples for different page types:

  • Home Page:

    <script>
async function initializeGSSDK() {
    window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
        provider: 'Custom',
        context: { pageType: 'home' }
    });
}
var gsSDKScript = document.createElement('script');
gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
gsSDKScript.onload = initializeGSSDK;
document.head.appendChild(gsSDKScript);
</script>

  • Product Detail Page:

    Include the product_id in the context for product detail pages.

    <script>
async function initializeGSSDK() {
    window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
        provider: 'Custom',
        context: { pageType: 'product_detail', product_id: '123' } // Replace '123' with actual product ID
    });
}
var gsSDKScript = document.createElement('script');
gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
gsSDKScript.onload = initializeGSSDK;
document.head.appendChild(gsSDKScript);
</script>

  • Cart and Checkout Pages:

    For cart and checkout pages, include the items in the cart within the context.

    <script>
async function initializeGSSDK() {
    var context = { pageType: 'cart', cart_items: [{ product_id: '1', quantity: '1' }] };
    window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
        provider: 'Custom',
        context: context
    });
}
var gsSDKScript = document.createElement('script');
gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
gsSDKScript.onload = initializeGSSDK;
document.head.appendChild(gsSDKScript);
</script>

Customer Authentication Management

If a customer is already authenticated, use the following JavaScript to log them in, the flag param_updateCartFromCustomer copies the cart from previous session into the new one

  • Add User Email: If an email address is available, it can be included in the login information. 

window.gsSDK.login('customer_id', {email: 'email@company.com', param_updateCartFromCustomer: true});

  • Logout:

    window.gsSDK.logout();

Adding Interactions

Tracking user interactions with products is crucial for personalization. Below are the methods to record various types of interactions.

Viewing a Product

When a user views a product, record the interaction as follows, replacing productId with the actual product ID.

window.gsSDK.addInteraction({
  "event": "view",
  "item": 'productId'
});

Liking a Product

To record when a user likes a product, use the following code snippet:

window.gsSDK.addInteraction({
  "event": "like",
  "item": 'productId'
});

Adding a Product to the Cart

When a product is added to the cart, record the interaction with details such as quantity and price:

window.gsSDK.addInteraction({
  "event": "cart",
  "item": productId,
  "quantity": 1,
  "price": 100
});

Removing a Product from the Cart

To record when a product is removed from the cart, use:

window.gsSDK.addInteraction({
  "event": "remove-cart",
  "item": productId,
  "quantity": 1,
  "price": 100
});

Handling Quantity Changes in the Cart

It's crucial to update interactions when the quantity of a product in the cart changes. Use the following logic to determine whether to record an add or remove interaction based on the new and old quantities:

const oldQuantity;
const newQuantity;

if (newQuantity > oldQuantity){
  window.gsSDK.addInteraction({
    "event": "cart",
    "item": productId,
    "quantity": newQuantity - oldQuantity,
    "price": 100
  });
} else {
  window.gsSDK.addInteraction({
    "event": "remove-cart",
    "item": productId,
    "quantity": oldQuantity - newQuantity,
    "price": 100
  });
}

Clearing the Cart

For e-commerce platforms that allow users to clear the cart, record the interaction as follows:

window.gsSDK.addInteraction({
  "event": "clean-cart"
});

Completing a Purchase

Once a purchase is completed, record the state of the cart. If the transaction ID is known, include it as shown:

window.gsSDK.addInteractionState('cart');

// If transaction ID is known
window.gsSDK.addInteractionState('cart', { "transactionId": "1"});
PreviousVTEX

Last updated