Loading docs...

👋 Need help? Chat with us!

Unified JavaScript SDK

One SDK for all platforms. Auto-loads Meta Pixel, GA4, and Clarity based on your connected integrations.

Beginner12 min readUpdated 2025-01-03

Our Unified JavaScript SDK is the single integration point for all your tracking needs. Install once, and it automatically loads Meta Pixel, GA4 gtag.js, and Microsoft Clarity based on which platforms you've connected in your dashboard.

Key benefit: Your customers add ONE script, and all connected analytics platforms receive data automatically.

Installation

Add this snippet to your <head> section:

****`html

****`

Where to Find Your API Key

Go to Settings → Developer → API Keys
Click Create New Key
Select "Tracking" permission
Copy the key (shown only once!)

Platform-Specific Instructions

Platform	Where to Add
Shopify	Online Store → Themes → Edit code → theme.liquid → Before </head>
WordPress	Use "Insert Headers and Footers" plugin
Webflow	Project Settings → Custom Code → Head Code
Next.js	_app.tsx or layout.tsx with Script component
React	index.html or useEffect in App component

How It Works

The Unified SDK implements dual-track event delivery:

Track	Destination	Purpose
Server-side	AdsMAA Backend	CAPI, Measurement Protocol, attribution
Client-side	Meta Pixel, GA4, Clarity	Real-time pixels, heatmaps, sessions

Event Flow

****

output

 User Action → SDK → ┬─→ AdsMAA Server ─→ Meta CAPI                     │                  ├─→ GA4 Measurement Protocol                     │                  └─→ (Server-side processing)                     │                     └─→ Client-Side ───→ fbq() (Meta Pixel)                                        ├─→ gtag() (GA4)                                        └─→ clarity() (Heatmaps) ****

This ensures maximum data collection: server-side bypasses ad blockers, while client-side enables platform-specific features.

Auto-Loaded Platforms

The SDK checks your organization's connected integrations and only loads what's configured:

Platform	Loaded When	Script
Meta Pixel	Meta integration connected with Pixel ID	fbq.js
GA4	GA4 integration connected with Measurement ID	gtag.js
Microsoft Clarity	Clarity integration connected with Project ID	clarity.js

What Gets Forwarded

Event Type	Meta Pixel	GA4	Clarity
Page View	PageView	page_view	Page visit
View Content	ViewContent	view_item	Custom tag
Add to Cart	AddToCart	add_to_cart	Custom tag
Purchase	Purchase	purchase	Custom tag
Identify	Advanced Matching	user_id	identify()

No Configuration Needed

Once you connect a platform in Settings → Integrations, the SDK automatically includes it. No code changes required on customer websites.

Initialization Options

Basic

****

output

javascript adsmai('init', 'YOUR_API_KEY'); ****

With Options

****`javascript adsmai('init', 'YOUR_API_KEY', { // Debugging debug: false, // Log events to console

// Auto-tracking autoTrack: { pageviews: true, // Track on page load clicks: true, // Track button/link clicks forms: false, // Track form submissions scrollDepth: false, // Track scroll milestones },

// Privacy respectDoNotTrack: false, // Honor DNT header cookieDomain: 'auto', // Cookie domain (auto-detected)

// Performance batchEvents: true, // Batch multiple events batchSize: 10, // Max events per batch flushInterval: 2000, // Flush every 2 seconds }); ****`

Tracking Methods

Page Views

****`javascript // Basic adsmai('pageview');

// With properties adsmai('pageview', { pageType: 'product', category: 'shoes' }); ****`

Standard Events

****`javascript // View content (product page) adsmai('track', 'ViewContent', { contentId: 'SKU-12345', contentName: 'Running Shoes', contentCategory: 'Footwear', value: 89.99, currency: 'USD' });

// Add to cart adsmai('track', 'AddToCart', { contentId: 'SKU-12345', contentName: 'Running Shoes', quantity: 1, value: 89.99, currency: 'USD' });

// Initiate checkout adsmai('track', 'InitiateCheckout', { value: 149.99, currency: 'USD', numItems: 2, contents: [ { id: 'SKU-12345', quantity: 1, price: 89.99 }, { id: 'SKU-67890', quantity: 1, price: 59.99 } ] });

// Purchase adsmai('track', 'Purchase', { orderId: 'ORDER-123', value: 149.99, currency: 'USD', contents: [ { id: 'SKU-12345', quantity: 1, price: 89.99 }, { id: 'SKU-67890', quantity: 1, price: 59.99 } ] }); ****`

All Supported Events

Event	Description
PageView	Page loaded
ViewContent	Product/content viewed
Search	Search performed
AddToWishlist	Added to wishlist
AddToCart	Added to cart
InitiateCheckout	Checkout started
AddPaymentInfo	Payment info added
Purchase	Order completed
Lead	Lead generated
CompleteRegistration	Account created
Subscribe	Newsletter signup
StartTrial	Trial started
Contact	Contact form sent

Custom Events

****

output

javascript adsmai('track', 'CustomEvent', {   name: 'video_completed',   videoId: 'abc123',   duration: 120,   completionRate: 100 }); ****

Identity Resolution

The Identify Call

When you know who the user is, call identify():

****`javascript adsmai('identify', { // At minimum, provide email OR externalId email: '[email protected]',

// Optional but recommended externalId: 'user-12345', // Your internal user ID phone: '+14155551234', firstName: 'Jane', lastName: 'Smith',

// Custom properties traits: { plan: 'premium', signupDate: '2024-01-15' } }); ****`

When to Identify

Moment	Why
Login	Match anonymous activity to known user
Registration	Capture new user identity
Checkout	Email entered at checkout
Newsletter signup	Capture lead
Purchase	Ensure conversion is attributed

Privacy Note

All PII is hashed (SHA256) before transmission. We never store or transmit raw email addresses, phone numbers, or names.

Single Page App Support

React, Vue, Angular, and Next.js apps need special handling since pages don't reload.

React Router Example

****`javascript import { useEffect } from 'react'; import { useLocation } from 'react-router-dom';

function usePageTracking() { const location = useLocation();

useEffect(() => { // Track pageview on route change window.adsmai?.('pageview', { path: location.pathname, search: location.search }); }, [location]); } ****`

Next.js App Router

****`javascript // app/providers.tsx 'use client';

import { usePathname, useSearchParams } from 'next/navigation'; import { useEffect } from 'react';

export function Analytics() { const pathname = usePathname(); const searchParams = useSearchParams();

useEffect(() => { window.adsmai?.('pageview'); }, [pathname, searchParams]);

return null; } ****`

Debugging

Enable Debug Mode

****

output

javascript adsmai('init', 'YOUR_API_KEY', { debug: true }); ****

You'll see in the console:

****

output

 [AdsMAA] Initialized with key: sk_live_abc... [AdsMAA] Event queued: PageView {url: "/products/shoes"} [AdsMAA] Batch sent: 1 events [AdsMAA] Event queued: ViewContent {contentId: "SKU-123", value: 89.99} ****

Check the Event Queue

****

output

javascript console.log(window.adsmai.q);  // See pending events ****

Verify in Dashboard

Open your site in a new tab
Trigger some events
Go to Tracking → Live Events
Events should appear within seconds

Common Issues

Problem	Cause	Solution
No events appearing	Script not loading	Check browser console for errors
Events delayed	Batching enabled	Events batch every 2 seconds by default
User not matching	Not identified	Call adsmai('identify') with email
Double events	SDK loaded twice	Check you only have one script tag

Recap

Here's what you learned:

Install with one snippet in your site's <head>
Initialize with options for debugging and auto-tracking
Track standard events for e-commerce funnel
Identify users to enable cross-device tracking
Handle SPAs with route change listeners

The SDK is your foundation. Once it's installed correctly, everything else just works.

Next step: Test your tracking setup to verify events are flowing.

Key Takeaways

1One SDK loads all connected platforms automatically
2Dual-track: events go to server-side (CAPI) AND client-side platforms
3Meta Pixel, GA4 gtag.js, and Clarity load only when connected
4Under 5KB base + platform scripts loaded on-demand

Frequently Asked Questions

Will this slow down my website?

No. The SDK is under 5KB gzipped and loads asynchronously. It won't block page rendering. Most sites see zero impact on Core Web Vitals.

Does this work with Content Security Policy (CSP)?

Yes. Add 'cdn.adsmai.com' to your script-src directive. For inline scripts, use a nonce or hash.

Can I use this with Google Tag Manager?

Yes! Add the SDK as a Custom HTML tag that fires on All Pages. Then use dataLayer pushes to trigger adsmai() calls.

Was this article helpful?

Ask a question

Continue Reading

tracking

Conversion Tracking Deep Dive

Understand how server-side tracking works and why it captures 2x more data than browser pixels.

integrations

Managing API Keys

Create, secure, and rotate your API keys. Best practices for production deployments.

getting started

Quick Start Guide

Go from zero to tracking in under 10 minutes. No prior experience required.

Loading docs...

Unified JavaScript SDK

One SDK for all platforms. Auto-loads Meta Pixel, GA4, and Clarity based on your connected integrations.

Beginner12 min readUpdated 2025-01-03

Key benefit: Your customers add ONE script, and all connected analytics platforms receive data automatically.

Installation

Add this snippet to your <head> section:

****`html

****`

Where to Find Your API Key

Go to Settings → Developer → API Keys
Click Create New Key
Select "Tracking" permission
Copy the key (shown only once!)

Platform-Specific Instructions

Platform	Where to Add
Shopify	Online Store → Themes → Edit code → theme.liquid → Before </head>
WordPress	Use "Insert Headers and Footers" plugin
Webflow	Project Settings → Custom Code → Head Code
Next.js	_app.tsx or layout.tsx with Script component
React	index.html or useEffect in App component

How It Works

The Unified SDK implements dual-track event delivery:

Track	Destination	Purpose
Server-side	AdsMAA Backend	CAPI, Measurement Protocol, attribution
Client-side	Meta Pixel, GA4, Clarity	Real-time pixels, heatmaps, sessions

Event Flow

****

output

 User Action → SDK → ┬─→ AdsMAA Server ─→ Meta CAPI                     │                  ├─→ GA4 Measurement Protocol                     │                  └─→ (Server-side processing)                     │                     └─→ Client-Side ───→ fbq() (Meta Pixel)                                        ├─→ gtag() (GA4)                                        └─→ clarity() (Heatmaps) ****

This ensures maximum data collection: server-side bypasses ad blockers, while client-side enables platform-specific features.

Auto-Loaded Platforms

The SDK checks your organization's connected integrations and only loads what's configured:

Platform	Loaded When	Script
Meta Pixel	Meta integration connected with Pixel ID	fbq.js
GA4	GA4 integration connected with Measurement ID	gtag.js
Microsoft Clarity	Clarity integration connected with Project ID	clarity.js

What Gets Forwarded

Event Type	Meta Pixel	GA4	Clarity
Page View	PageView	page_view	Page visit
View Content	ViewContent	view_item	Custom tag
Add to Cart	AddToCart	add_to_cart	Custom tag
Purchase	Purchase	purchase	Custom tag
Identify	Advanced Matching	user_id	identify()

No Configuration Needed

Once you connect a platform in Settings → Integrations, the SDK automatically includes it. No code changes required on customer websites.

Initialization Options

Basic

****

output

javascript adsmai('init', 'YOUR_API_KEY'); ****

With Options

****`javascript adsmai('init', 'YOUR_API_KEY', { // Debugging debug: false, // Log events to console

// Privacy respectDoNotTrack: false, // Honor DNT header cookieDomain: 'auto', // Cookie domain (auto-detected)

// Performance batchEvents: true, // Batch multiple events batchSize: 10, // Max events per batch flushInterval: 2000, // Flush every 2 seconds }); ****`

Tracking Methods

Page Views

****`javascript // Basic adsmai('pageview');

// With properties adsmai('pageview', { pageType: 'product', category: 'shoes' }); ****`

Standard Events

****`javascript // View content (product page) adsmai('track', 'ViewContent', { contentId: 'SKU-12345', contentName: 'Running Shoes', contentCategory: 'Footwear', value: 89.99, currency: 'USD' });

// Add to cart adsmai('track', 'AddToCart', { contentId: 'SKU-12345', contentName: 'Running Shoes', quantity: 1, value: 89.99, currency: 'USD' });

All Supported Events

Event	Description
PageView	Page loaded
ViewContent	Product/content viewed
Search	Search performed
AddToWishlist	Added to wishlist
AddToCart	Added to cart
InitiateCheckout	Checkout started
AddPaymentInfo	Payment info added
Purchase	Order completed
Lead	Lead generated
CompleteRegistration	Account created
Subscribe	Newsletter signup
StartTrial	Trial started
Contact	Contact form sent

Custom Events

****

output

javascript adsmai('track', 'CustomEvent', {   name: 'video_completed',   videoId: 'abc123',   duration: 120,   completionRate: 100 }); ****

Identity Resolution

The Identify Call

When you know who the user is, call identify():

****`javascript adsmai('identify', { // At minimum, provide email OR externalId email: '[email protected]',

// Optional but recommended externalId: 'user-12345', // Your internal user ID phone: '+14155551234', firstName: 'Jane', lastName: 'Smith',

// Custom properties traits: { plan: 'premium', signupDate: '2024-01-15' } }); ****`

When to Identify

Moment	Why
Login	Match anonymous activity to known user
Registration	Capture new user identity
Checkout	Email entered at checkout
Newsletter signup	Capture lead
Purchase	Ensure conversion is attributed

Privacy Note

All PII is hashed (SHA256) before transmission. We never store or transmit raw email addresses, phone numbers, or names.

Single Page App Support

React, Vue, Angular, and Next.js apps need special handling since pages don't reload.

React Router Example

****`javascript import { useEffect } from 'react'; import { useLocation } from 'react-router-dom';

function usePageTracking() { const location = useLocation();

useEffect(() => { // Track pageview on route change window.adsmai?.('pageview', { path: location.pathname, search: location.search }); }, [location]); } ****`

Next.js App Router

****`javascript // app/providers.tsx 'use client';

import { usePathname, useSearchParams } from 'next/navigation'; import { useEffect } from 'react';

export function Analytics() { const pathname = usePathname(); const searchParams = useSearchParams();

useEffect(() => { window.adsmai?.('pageview'); }, [pathname, searchParams]);

return null; } ****`

Debugging

Enable Debug Mode

****

output

javascript adsmai('init', 'YOUR_API_KEY', { debug: true }); ****

You'll see in the console:

****

output

 [AdsMAA] Initialized with key: sk_live_abc... [AdsMAA] Event queued: PageView {url: "/products/shoes"} [AdsMAA] Batch sent: 1 events [AdsMAA] Event queued: ViewContent {contentId: "SKU-123", value: 89.99} ****

Check the Event Queue

****

output

javascript console.log(window.adsmai.q);  // See pending events ****

Verify in Dashboard

Open your site in a new tab
Trigger some events
Go to Tracking → Live Events
Events should appear within seconds

Common Issues

Problem	Cause	Solution
No events appearing	Script not loading	Check browser console for errors
Events delayed	Batching enabled	Events batch every 2 seconds by default
User not matching	Not identified	Call adsmai('identify') with email
Double events	SDK loaded twice	Check you only have one script tag

Recap

Here's what you learned:

Install with one snippet in your site's <head>
Initialize with options for debugging and auto-tracking
Track standard events for e-commerce funnel
Identify users to enable cross-device tracking
Handle SPAs with route change listeners

The SDK is your foundation. Once it's installed correctly, everything else just works.

Next step: Test your tracking setup to verify events are flowing.

Key Takeaways

1One SDK loads all connected platforms automatically
2Dual-track: events go to server-side (CAPI) AND client-side platforms
3Meta Pixel, GA4 gtag.js, and Clarity load only when connected
4Under 5KB base + platform scripts loaded on-demand

Frequently Asked Questions

Will this slow down my website?

No. The SDK is under 5KB gzipped and loads asynchronously. It won't block page rendering. Most sites see zero impact on Core Web Vitals.

Does this work with Content Security Policy (CSP)?

Yes. Add 'cdn.adsmai.com' to your script-src directive. For inline scripts, use a nonce or hash.

Can I use this with Google Tag Manager?

Yes! Add the SDK as a Custom HTML tag that fires on All Pages. Then use dataLayer pushes to trigger adsmai() calls.

Was this article helpful?

Ask a question

Continue Reading

tracking