SiteVibes Integration Guide for Headless Sites

Modified on Wed, 27 Nov, 2024 at 10:20 AM

This guide covers how to implement SiteVibes on a headless site. Since traditional script managers may not be available for headless implementations, you'll need to manually add the required scripts to your front-end.

Prerequisites

A SiteVibes account
Access to your front-end codebase
Your SiteVibes Development pixel key (found in SiteVibes dashboard under Settings -> Install)

Installation Steps

1. Basic SiteVibes Integration

Log into your SiteVibes dashboard
Navigate to Settings -> Install
Copy your unique SiteVibes pixel script
Add the script to your application's <head> section. This is typically done in your main layout component or HTML template.

Example pixel script:

<!-- Pixel Code for SiteVibes -->
<script id="sv-pixel-script" src="<https://app.sitevibes.com/js/pixel.js?key=test-key-19bb-4681-afc6-627444237c39>" async></script>
<!-- END Pixel Code -->

Note: Replace the key parameter in the example with your unique SiteVibes pixel key from the dashboard.

2. Product Data Integration

On your Product Detail Page (PDP), add the following script:

<script>
    var SiteVibesProduct = {
        product_id: "[YOUR_PRODUCT_ID]",
        product_sku: "[PRODUCT_SKU]", // optional
        product_variant_id: "[VARIANT_ID]", // optional
        name: "[PRODUCT_NAME]",
        description: "[PRODUCT_DESCRIPTION]",
        url: "[PRODUCT_URL]",
        image_url: "[PRODUCT_IMAGE_URL]",
        category_name: "[CATEGORY_NAME]",
        brand_name: "[BRAND_NAME]",
        quantity: [QUANTITY],
        quantity_in_store: [STORE_QUANTITY], // optional
        price: [PRICE],
        price_range: [MIN_PRICE, MAX_PRICE], // optional
        price_sale: [SALE_PRICE], // optional
        price_sale_range: [MIN_SALE_PRICE, MAX_SALE_PRICE], // optional
        groups: ["New", "Promotion"], // optional
        variants: [ // optional
            {
                id: "[VARIANT_ID]",
                name: "[VARIANT_NAME]",
                sku: "[VARIANT_SKU]"
            }
        ]
    };
</script>

3. Order Tracking Integration

Add the following script to your order confirmation page:

<script>
    var SiteVibesOrderData = {
        email: "[CUSTOMER_EMAIL]",
        firstName: "[CUSTOMER_FIRST_NAME]",
        lastName: "[CUSTOMER_LAST_NAME]",
        orderId: "[ORDER_ID]",
        paymentMethods: "credit_card,gift_card", // optional - list of payment methods. Standard methods ("credit_card", "gift_card", "store_credit", "paypal", "apple_pay", "google_pay")
        orderItems: [
            {
                product_id: "[PRODUCT_ID]",
                product_variant_id: "[VARIANT_ID]", // optional
                quantity: [QUANTITY],
                unit_price: [UNIT_PRICE]
            }
        ],
        coupons: ["[COUPON_CODE]"] // optional
    };
</script>

4. Single Page Application (SPA) Support

For React or other SPA frameworks, trigger the following event whenever the page content updates:

SiteVibesEvents.pageRefresh()

Consider calling this event:

After route changes
After major component updates
When dynamic content loads

Verification

Use browser developer tools to verify that all scripts are loading correctly
Check the network tab to ensure data is being sent to SiteVibes
Contact SiteVibes support to confirm proper data transmission
Test the integration across different user scenarios (logged in, guest, purchase flow)

5. Loyalty Application Support

The Loyalty Application Support allows you to integrate SiteVibes with your loyalty program by tracking authenticated users and their activities.

Implementation Steps

Add the following script to your authentication logic:

<script>
    var SiteVibesStoreType = "custom";
    var SiteVibesLoggedInUserData = {
        isLoggedIn: true,          // Required: Boolean indicating if user is logged in
        userToken: "828812",       // Required: Unique identifier for the user in your system
        userEmail: "customer@email.com",  // Required: User's email address
        userName: "firstName lastName",    // Required: User's full name
        cartTotal: 248.99          // Required: Current cart value in decimal format
    };
</script>

When to Implement

Add this script:

After successful user login
On page load if user is already authenticated
After cart updates that affect the total

Data Requirements

Field	Type	Description	Required
isLoggedIn	Boolean	Must be true for loyalty tracking	Yes
userToken	String	Unique identifier that remains consistent across sessions	Yes
userEmail	String	Valid email address in standard format	Yes
userName	String	User's full name (first and last name)	Yes
cartTotal	Number	Current cart value (decimal format)	Yes

Verification

Check browser console for script loading errors
Verify user data appears in SiteVibes dashboard under Loyalty section
Confirm tracking events are firing in Network tab after login

Common Issues

User not tracked: Verify all required fields are present and properly formatted
Inconsistent tracking: Ensure userToken remains consistent across sessions
Data not updating: Check script triggers on cart updates and authentication state changes

Troubleshooting

Common issues and solutions:

Scripts not loading
- Verify script placement in the <head> section
- Check for JavaScript console errors
- Ensure your SiteVibes pixel key is correct
Data not tracking
- Verify proper object structure in SiteVibes scripts
- Ensure all required fields contain valid data
- Check network requests for successful data transmission