@masivo/client

Official Masivo SDK for web applications — event tracking and customer engagement in browser environments.

Important: This SDK requires a CLIENT API key. Do not use SERVER API keys — they will be rejected and the SDK will warn you about exposed server credentials. Create a CLIENT key in the Masivo dashboard.

React Native / mobile app? Use @masivo/rn instead — it includes push notification and in-app messaging support without any browser dependencies.

Installation

npm install @masivo/client

pnpm add @masivo/client

yarn add @masivo/client

Quick Start

import { createClient } from "@masivo/client";

const masivo = createClient({ apiKey: "your-client-api-key" });

await masivo.sendAnalyticsEvent({
  type: "ADD_TO_CART",
  customer_id: "customer-123",
  brand_id: "brand-456",
  product: {
    sku: "SKU-001",
    amount: 1,
    value: 29.99
  }
});

Events are automatically flushed when the browser tab is hidden or the page is unloaded, so no events are lost on navigation.

Events are sent on the analytics path: they feed tracking, journeys, and related flows without applying behavioral or punch-card loyalty rewards from the browser. Use your backend with a SERVER key when you need full loyalty campaign execution.

What this package adds over @masivo/core

@masivo/client is a thin wrapper around @masivo/core that registers two browser lifecycle listeners:

• pagehide — flushes buffered events when the user navigates away.
• visibilitychange (hidden) — flushes buffered events when the tab goes to background.

Both listeners are registered only if window and document exist, so the package is safe to import in SSR environments (Next.js, Remix, etc.) without throwing errors.

Allowed Event Types

This SDK uses CLIENT API keys, which can only emit:

• Tracking events — ADD_TO_CART, EMPTY_CART, and other tracking types.
• Custom event types — Any custom event type you have created in the Masivo platform.

Default event types like PURCHASE, ABANDONED_CART, BIRTHDAY, REGISTRATION, and TIER_ADJUSTMENT are not allowed from the client SDK. These must be sent from your backend using a SERVER API key directly via the Masivo REST API.

API

createClient(config)

Creates a new Masivo client instance. All core functionality (auth, batching, token refresh) comes from @masivo/core.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | config.apiKey | string | Yes | Your Masivo CLIENT API key | | config.brandId | string \| null | No | Default brand ID injected into events that have a platform but no explicit brand_id |

Returns a MasivoClient:

client.sendAnalyticsEvent(event)

Sends an event to Masivo on the analytics path.

| Field | Type | Required | Description | | --- | --- | --- | --- | | type | string | Yes | Event type (e.g. ADD_TO_CART, custom type) | | customer_id | string | Yes | External customer identifier | | brand_id | string \| null | Yes | Brand identifier, null if not applicable | | ...rest | unknown | No | Any additional event data |

Returns Promise<SendEventResult>:

{
  success: boolean;
  status: number;
  data: unknown;
}

client.flush()

Forces an immediate send of all buffered events.

await masivo.flush();

client.destroy()

Stops the background token refresh and clears internal state. Call this on logout.

masivo.destroy();

Error Handling

All error classes are re-exported from @masivo/core:

import { createClient, MasivoError, MasivoServerKeyError, MasivoAuthError, MasivoNetworkError } from "@masivo/client";

const masivo = createClient({ apiKey: "your-client-api-key" });

try {
  await masivo.sendAnalyticsEvent({
    type: "ADD_TO_CART",
    customer_id: "customer-123",
    brand_id: null
  });
} catch (error) {
  if (error instanceof MasivoServerKeyError) {
    console.error(error.message);
  } else if (error instanceof MasivoNetworkError) {
    console.error("Network error:", error.message);
  } else if (error instanceof MasivoAuthError) {
    console.error("Auth error:", error.message, error.details);
  } else if (error instanceof MasivoError) {
    console.error("API error:", error.status, error.message);
  }
}

| Error class | When | Properties | | --- | --- | --- | | MasivoServerKeyError | SERVER API key used instead of CLIENT | message | | MasivoNetworkError | Fetch fails (no connectivity, DNS, etc.) | message | | MasivoAuthError | Authorization fails (invalid/expired key) | message, status, details | | MasivoError | API returns an error response | message, status, details |

Usage with Next.js

// lib/masivo.ts
import { createClient } from "@masivo/client";

// Initialize once — safe to import in client components
export const masivo = createClient({ 
  apiKey: process.env.NEXT_PUBLIC_MASIVO_CLIENT_KEY!,
  brandId: process.env.NEXT_PUBLIC_MASIVO_BRAND_ID  // optional
});

// In a client component
"use client";
import { masivo } from "@/lib/masivo";

masivo.sendAnalyticsEvent({
  type: "ADD_TO_CART",
  customer_id: session.user.id,
  brand_id: null,
  product: { sku, value }
});

Batching Behavior

Events are queued and sent in bulk:

| Trigger | Condition | | --- | --- | | Queue size | Flush when 100 events are queued | | Idle | Flush after 30 seconds with no new events | | Max wait | Flush after 60 seconds regardless of activity | | Page hide | Flush automatically on navigation/tab close | | Visibility hidden | Flush automatically when tab goes to background | | Manual | Call client.flush() to send immediately |

Compatibility

• Browsers (built-in fetch)
• Node.js >= 18 — SSR safe, browser listeners are skipped
• React Native — safe to import but use @masivo/rn for the full mobile experience

Zero external dependencies.

Links

• Masivo Documentation
• Masivo Dashboard
• @masivo/core — underlying core package
• @masivo/rn — React Native SDK

License

MIT