@antelopejs/interface-dms-marketing

The AntelopeJS interface to read aggregated first-party analytics of the DMS marketing module from any module, and to ship marketing content as code.

What it does

• Reads the click heatmap of one page path across a tenant's websites, aggregated on the implementer's grid (GetClickHeatmap).
• Returns normalized points with the clicked element's anchor, so an overlay stays stable across window sizes.
• Lets you show marketing data to tenant users on your own pages, since every /modules/ page of the DMS is reserved to the platform owner.
• Declares websites and funnels with their A/B splits from code (EnsureWebsite, EnsureFunnel). A declaration writes once per id, and a record that already exists is left as it is.
• Declares page snapshots, the backdrops of the heatmaps, for pages the tracker cannot capture (EnsurePageSnapshot).
• Imports historical analytics through the live collection pipeline, once per import id (ImportAnalytics), for a demo instance or a move from another tool.
• Keeps your module independent of the implementation, @antelopejs/dms-marketing.

Install

Add the interface as an optional dependency of the module that reads analytics. A call made before a module implements the interface waits for one, and a storage failure rejects, so catch the rejection where analytics are optional.

pnpm add --save-optional @antelopejs/interface-dms-marketing

Quick start

import { GetClickHeatmap } from "@antelopejs/interface-dms-marketing";

export async function pricingHeatmap(tenantId: string) {
  try {
    return await GetClickHeatmap({ tenantId, path: "/pricing" });
  } catch {
    return null;
  }
}

Without from and to, the heatmap covers the last 7 days. Pass an authenticated tenant id only.

Declare content from a Hook.TENANT_BEING_PROVISIONED handler. The DMS fires it once per tenant, when the tenant is created, the default tenant included. All four content functions require tenantId, and a missing or blank value, or one with surrounding whitespace, rejects. The marketing module neither provisions nor authorizes tenants.

import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
import { EnsureFunnel, EnsureWebsite } from "@antelopejs/interface-dms-marketing";

async function writeShopContent(tenantId: string) {
  await EnsureWebsite({ tenantId, id: "shop", name: "Shop", domain: "shop.example.com" });
  await EnsureFunnel({
    tenantId,
    id: "shop-checkout",
    websiteId: "shop",
    name: "Checkout",
    steps: [
      { kind: "url", value: "/cart" },
      { kind: "custom", value: "order_placed" },
    ],
  });
}

export function construct() {
  RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
    await writeShopContent(tenantId);
  });
}

Compatibility

A @antelopejs/dms-marketing release implements one minor line of this interface. The @antelopejs/interface-dms-marketing row of the compatibility block in the module README gives that range. Use a module release whose range covers the interface release your code imports. A module release that predates a function never implements it, and a call to that function waits forever. The interface declares this peer dependency:

| Package | Supported | Tested with | | ---------------------------- | ---------------- | ----------- | | @antelopejs/interface-core | >=0.2.4 <1.0.0 | 0.4.0 |

Documentation

• Consumer reference: the heatmap query, its results, limits and tenant boundaries, the content declarations and the analytics import
• Extending the marketing module: the interface, the tracker's JavaScript API and the HTTP API
• Marketing module guide

Contributing

This package lives in the AntelopeJS/dms-marketing pnpm workspace, next to the module that implements it. Read CONTRIBUTING.md and the repository README for the development commands. Release this package before the module that implements it.

License

Apache-2.0