Envive Analytics SDK

We provide a lightweight SDK for reporting specific events on the frontend to Envive.

Quick Start

1. Install the SDK via npm/yarn or use the CDN snippet

2. Get your API key from the Envive team (ENVIVE_PUBLIC_KEY)

3. Identify users with identifyUser() OR pass identityOptions with every tracking call

4. Track events like checkout completion and add-to-cart actions

Pre-Launch Checklist

• identifyUser() called once after user login/recognition

• User ID is stable (not random UUID or session-based)

• idType parameter is a descriptive label for where the ID comes from (e.g., "shopify-client-id")

• No events fired before user identification

• Test events appear correctly in Envive dashboard

Installation

To install @envive-ai/analytics Install as follows:

npm

npm install @envive-ai/analytics

yarn

GTM

Snippet

Usage

NPM/Yarn Usage

import { EnviveAnalytics, EnviveAnalyticsOptions } from '@envive-ai/analytics'

const options: EnviveAnalyticsOptions = {
  apiKey: 'ENVIVE_PUBLIC_KEY', 
}

const envive = new EnviveAnalytics(options) 
envive.identifyUser("some-user-id" /* merchant user id */, "shopify-user-id" /* id-type */)
envive.trackAddToCart({id: "1", quantity: 1, price: 19.99, currencyCode: "usd"});

CDN Usage

<script>
window._enviveOptions = {
  apiKey: 'ENVIVE_PUBLIC_KEY',
}
//...snippet
</script>
<script>
envive.identifyUser("shopify_customer_123", "shopify-user-id")
envive.trackAddToCart({id: "1", quantity: 1, price: 19.99, currencyCode: "usd"});
</script>

User Identification

Choose one approach (required):

1. Call identifyUser() once when the user is recognized and before calling any tracking methods

OR

1. Pass identityOptions with every tracking call

⚠️ Critical: If users are not properly identified, events cannot be attributed and analytics will not work.

User ID Guidelines

Requirements (for both methods):

• Use a stable, persistent ID from your platform (never random UUIDs)

• Always include idType to describe where the ID came from. See idType for more information.

Correct ID sources:

• ✅ Shopify clientId

• ✅ Internal platform user ID

• ✅ BigCommerce SHOP_SESSION_TOKEN

• ✅ Magento customer_id (if configured to persist long-term)

Incorrect ID sources:

• ❌ Random UUIDs

• ❌ Session IDs

• ❌ Cart IDs

• ❌ Auto-generated values

idType

idType is a descriptive label for the user ID you send to Envive. It is highly recommended to provide an idType value to maintain unique ID namespaces.

Set idType to a kebab-case string that describes where the ID came from, such as:

• shopify-client-id

• magento-user-id

• crm-user-id

Method 1: identifyUser() (Recommended)

Call once before any tracking calls. The id that you choose must not change for the lifetime of the user.

identifyUser(merchantUserId: string, idType: string): void

// Example
envive.identifyUser("shopify_customer_123", "shopify-user-id")

See User ID Guidelines and idType for more information on how to use these parameters.

Method 2: identityOptions Parameter

If you are not using identifyUser(), include this object with every tracking call:

type IdentityOptions = {
  merchantUserId: string;
  idType: string;
}

See User ID Guidelines and idType for more information on how to use these parameters.

Using identifyUser() Without Shopify

If your platform is not on Shopify, you must pass the stable user ID that your platform already uses.

Examples:

• CRM user ID

• Internal platform account ID

• Authentication system user ID

Do not use session IDs, cart IDs, browser-generated IDs, or random UUIDs.

See User ID Guidelines and idType for more information on how to use these parameters.

Event Tracking Methods

Note: If not using identifyUser(), include identityOptions with every tracking call.

trackCheckoutComplete

When a user completes a purchase, it is typically triggered on the thank-you page.

Equivalent to Shopify checkout_completed event.

⚠️ IdentityOptions Required (if identifyUser is not used)

Important: If you do not call identifyUser() before any track events, you must include the identityOptions argument with every single tracking call. Failing to do so will cause attribution to break.

type CheckoutEventProperties = {
  total: number;
  currencyCode: string;
  products: Array<{
    id: string;
    quantity: number;
    price: number;
    [x: string]: any;
  }>;
  [x: string]: any; // Additional optional properties
};

type IdentityOptions = {
  merchantUserId: string;
  idType: string;
};

// Required EventProperties 
const eventProperties: CheckoutEventProperties = {
  "total": 100,
  "currencyCode": "usd",
  "products": [
    {
      "id": "123",
      "price": 100,
      "quantity": 1
    }
  ]
}

// Optional Property
const identity: IdentityOptions | undefined = {
  merchantUserId: "some-shopify-client-id-string-here",
  idType: "shopify-client-id",
}
  
trackCheckoutComplete(eventProperties, identity): void

trackAddToCartClicked

When a user adds a product to their cart.

Equivalent to the Shopify product_added_to_cart event.

⚠️ IdentityOptions Required (if identifyUser is not used)

Important: If you do not call identifyUser() before any track events, you must include the identityOptions argument with every single tracking call. Failing to do so will cause attribution to break.

type AddToCartEventProperties = {
  id: string;
  quantity: number;
  price: number;
  currencyCode: string;
  [x: string]: any; // Additional optional properties
};

// Required EventProperties 
const eventProperties: AddToCartEventProperties = {
  "id": "123",
  "price": 100,
  "currencyCode": "usd",
  "quantity": 1
}

// Optional Property
const identity: IdentityOptions | undefined = {
  merchantUserId: "some-magento-id-string-here",
  idType: "magento-user-id"
}

trackAddToCartClicked(eventProperties, identity): void 

trackCustomConversion

Used to track a non-standard conversion defined by the merchant.

⚠️ IdentityOptions Required (if identifyUser is not used)

Important: If you do not call identifyUser() before any track events, you must include the identityOptions argument with every single tracking call. Failing to do so will cause attribution to break.

type CustomConversionEventProperties = {
  revenue: number;
  currencyCode: string;
  [x: string]: any; // Additional optional properties
};

// Required EventProperties 
const eventProperties: CustomConversionEventProperties = {
  "currencyCode": "usd",
  "revenue": 10
}

// Optional Property 
const identity: IdentityOptions | undefined = {
  merchantUserId: "some-magento-id-string-here",
  idType: "magento-user-id"
}

trackCustomConversion(eventProperties, identity): void

trackPageViewed

⚠️ IdentityOptions Required (if identifyUser is not used)

Important: If you do not call identifyUser() before any track events, you must include the identityOptions argument with every single tracking call. Failing to do so will cause attribution to break.

// Required EventProperties 
const properties: Record<string, any> = {
  "productId": "some-product-id"
}

// Optional Property
const identity: IdentityOptions | undefined = {
  merchantUserId: "some-sales-force-commerce-user-id-string-here",
  idType: "sales-force-commerce-user-id"
}

trackPageViewed(properties, identity): void

Common Mistakes

Most frequent integration issues:

• Missing identifyUser() - Events can't be linked across sessions

• Random UUIDs - Creates new "users" every page load

• Late identification - Events before identifyUser() won't be attributed

• Unstable IDs - Don't use session/cart IDs or localStorage values

• Platform confusion - Use your platform's actual user ID, not Shopify-specific IDs on other platforms

Server Side Usage

Note: When using the analytics SDK server-side, an enviveUserId is neither present nor required in any SDK API call methods.

However, it is critical that:

1. IdentifyUser is called somewhere in the user's client-side journey (on your website)

2. All Track__ Methods are supplied with the identity information

To Summarize:

SDK method call	Location	Instructions
IdenfiyUser or Track____ method call with identity payload included	Website	IdenfiyUser or Track with identity included must be called at least once in the user's client-side journey
Track____ methods only. No IdentifyUser calls necessary.	Server Side (eg: Lambda functions, Azure Functions, ECS Tasks etc)	Call as needed to instrument events such as "Checkout Begin", "Checkout Complete" or "Commerce Transaction Complete" and always include the identity parameter

Example Implementations

Check out the example minimal implementations of using this SDK.

Platform	Language	Code
Shopify Hydrogen	React	https://github.com/spiffy-ai/envive-examples/blob/main/analytics/react/README.md