@ action-reach/web-sdk (英语)

网络 SDK 用于 积极接触情报 ——轻量级事件跟踪,身份解析,应用中消息(覆盖,嵌入式卡片,交互式部件),并进行网络推.

12KB弹出 | < 1KB 自动加载器 | 对页面负荷的零影响

先决条件

在整合之前,您需要:

1. 写入密钥 - 从你的主动接触情报仪表板上取回 设置 > 开发者 > API 密钥。 。 。 .
2. API 主机 — 您的单元格端点 URL( 在登入时提供) .

说明: 写入密钥为 a 可公布的标识符 (如花纹可发布密钥). 在客户端代码中包含是安全的。 它只能发送事件——它不能读取数据,修改配置,或访问其他租户. 永远不要用你的 密钥 在客户端代码.

安装

国家预防机制(建议)

npm install @active-reach/web-sdk

CDN (同步装入器)

将此片段添加到您的 <head> 标签。 ASync加载器队列所有调用,直到SDK满载——零屏蔽.

<script>
  !function(){var e=window.aegis=window.aegis||[];if(!e.invoked){e.invoked=!0,e.methods=["init","track","identify","page","group","alias","reset","flush","use","debug","setCell","getCellInfo","getAnonymousId","getUserId","getSessionId","setConsent","grantConsent","denyConsent","hasConsent","getConsentPreferences","onConsentChange"],e.factory=function(t){return function(){var n=Array.prototype.slice.call(arguments);return n.unshift(t),e.push(n),e}};for(var t=0;t<e.methods.length;t++){var n=e.methods[t];e[n]=e.factory(n)}e.load=function(t,n){var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=n&&n.cdnUrl?n.cdnUrl:"https://platform.active-reach.ai/sdk/aegis.min.js",o.onerror=function(){window.console&&console.error("Aegis SDK failed to load")};var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(o,r),e._loadOptions={key:t,options:n}},e.SNIPPET_VERSION="1.0.0"}}();

  aegis.load('YOUR_WRITE_KEY');
  aegis.init('YOUR_WRITE_KEY', {
    api_host: 'https://YOUR_CELL.activereach.ai'
  });
</script>

快速启动

国家预防机制/环境单元

import aegis from '@active-reach/web-sdk';

await aegis.init('YOUR_WRITE_KEY', {
  api_host: 'https://YOUR_CELL.activereach.ai',
  auto_page_view: true,
});

// Track an event
aegis.track('Purchase Completed', {
  order_id: 'ORD-123',
  revenue: 99.99,
  currency: 'INR',
});

// Identify a user
aegis.identify('user_123', {
  email: '[email protected]',
  name: 'Priya Sharma',
  plan: 'premium',
});

反应

import { AegisProvider, useAegis, useTrackEvent } from '@active-reach/web-sdk/react';

function App() {
  return (
    <AegisProvider
      writeKey="YOUR_WRITE_KEY"
      config={{ api_host: 'https://YOUR_CELL.activereach.ai', auto_page_view: true }}
    >
      <Dashboard />
    </AegisProvider>
  );
}

function Dashboard() {
  const { isReady } = useAegis();
  const trackEvent = useTrackEvent();

  return (
    <button onClick={() => trackEvent('Button Clicked', { button: 'CTA' })}>
      Track Event
    </button>
  );
}

下一个.js

// app/providers.tsx
'use client';

import { AegisProvider } from '@active-reach/web-sdk/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AegisProvider
      writeKey={process.env.NEXT_PUBLIC_AEGIS_WRITE_KEY!}
      config={{ api_host: process.env.NEXT_PUBLIC_AEGIS_API_HOST! }}
    >
      {children}
    </AegisProvider>
  );
}

配置

await aegis.init('YOUR_WRITE_KEY', {
  // Required
  api_host: string;

  // Batching & Performance
  batch_size?: number;           // default: 10
  batch_interval?: number;       // default: 1000ms

  // Data Capture
  capture_utm?: boolean;         // default: true
  capture_referrer?: boolean;    // default: true
  auto_page_view?: boolean;      // default: false

  // Session
  session_timeout?: number;      // default: 1800000 (30 min)

  // Privacy & Consent
  respect_dnt?: boolean;         // default: true
  enable_consent_mode?: boolean; // default: false
  wait_for_consent?: boolean;    // default: false
  default_consent?: {
    analytics?: boolean;         // default: false
    marketing?: boolean;         // default: false
    functional?: boolean;        // default: true
  };
  integrate_onetrust?: boolean;
  integrate_cookiebot?: boolean;
  integrate_google_consent_mode?: boolean;

  // Cookie
  cross_domain_tracking?: boolean; // default: false
  cookie_domain?: string;
  secure_cookie?: boolean;         // default: true

  // Offline & Retry
  enable_offline_mode?: boolean;   // default: true
  max_offline_events?: number;     // default: 100
  retry_failed_requests?: boolean; // default: true
  max_retries?: number;            // default: 3

  // Regional Cell Selection
  cell_endpoints?: CellEndpoint[];
  preferred_region?: string;
  auto_region_detection?: boolean; // default: true

  // Debug
  debug?: boolean;                 // default: false
});

核心 API

aegis.track(eventName, properties?)

跟踪自定义事件 .

aegis.track('Product Viewed', {
  product_id: 'SKU-12345',
  product_name: 'Leather Jacket',
  price: 199.99,
  category: 'Outerwear',
});

aegis.identify(userId, traits?)

识别用户和关联特征.

aegis.identify('user_123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'premium',
});

aegis.page(name?, properties?)

跟踪页面视图 .

aegis.page('Product Page', { product_id: 'SKU-12345' });

aegis.group(groupId, traits?)

与一个团体(公司、组织)联系用户.

aegis.group('company_789', {
  name: 'Acme Corp',
  industry: 'Technology',
  employees: 500,
});

aegis.alias(newUserId)

合并两个用户身份.

aegis.alias('permanent_user_id');

aegis.reset()

登录时清除用户身份 。 生成新的匿名身份 .

aegis.reset();

aegis.flush()

强制发送所有已排队的事件 .

await aegis.flush();

电子商务追踪

为标准化电子商务活动搭建的助手 aegis.ecommerce数字 :

import aegis from '@active-reach/web-sdk';

// Product discovery
aegis.ecommerce.productViewed({
  product_id: 'SKU-123',
  name: 'Leather Jacket',
  price: 4999,
  currency: 'INR',
  category: 'Outerwear',
  brand: 'Acme',
  variant_id: 'black_xl',
  variant_label: 'Black XL',
});

aegis.ecommerce.productListViewed({
  list_name: 'New Arrivals',
  category: 'Outerwear',
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 }],
});

aegis.ecommerce.searchPerformed({ query: 'leather jacket', results_count: 12 });

// Cart
aegis.ecommerce.addToCart({
  product_id: 'SKU-123',
  name: 'Leather Jacket',
  price: 4999,
  quantity: 1,
});

aegis.ecommerce.removeFromCart({ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 });

aegis.ecommerce.cartViewed({
  cart_id: 'cart_456',
  value: 4999,
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
});

// Checkout
aegis.ecommerce.checkoutStarted({
  value: 4999,
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
  coupon: 'WELCOME10',
  shipping: 99,
  tax: 450,
});

aegis.ecommerce.checkoutStep(2, { payment_method: 'UPI' });

// Order
aegis.ecommerce.orderCompleted({
  order_id: 'ORD-789',
  value: 5548,
  revenue: 4999,
  shipping: 99,
  tax: 450,
  payment_method: 'UPI',
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
});

aegis.ecommerce.orderRefunded('ORD-789', 4999);

// Coupons
aegis.ecommerce.couponApplied({ coupon_code: 'WELCOME10', discount_value: 500, discount_type: 'fixed' });
aegis.ecommerce.couponRemoved({ coupon_code: 'WELCOME10' });

// Wishlist
aegis.ecommerce.wishlistItemAdded({
  product: { product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 },
});

// Promotions
aegis.ecommerce.promotionViewed({ name: 'Summer Sale', promotion_id: 'promo_1', creative: 'banner_hero' });
aegis.ecommerce.promotionClicked({ name: 'Summer Sale', promotion_id: 'promo_1' });

所有电子商务方法

反应钩

从 @active-reach/web-sdk/react数字 :

同意管理

建设支持GDPR/CCPA合规.

// Set preferences
aegis.setConsent({ analytics: true, marketing: false, functional: true });

// Grant / deny
aegis.grantConsent();           // all categories
aegis.grantConsent('analytics'); // specific category

aegis.denyConsent();
aegis.denyConsent('marketing');

// Query
aegis.hasConsent('analytics');   // boolean
aegis.getConsentPreferences();   // full object

// Listen for changes
const unsubscribe = aegis.onConsentChange((prefs) => {
  console.log('Consent updated:', prefs);
});

第三方一体化

// OneTrust
aegis.init('KEY', { enable_consent_mode: true, integrate_onetrust: true });

// Cookiebot
aegis.init('KEY', { enable_consent_mode: true, integrate_cookiebot: true });

// Google Consent Mode v2
aegis.init('KEY', { enable_consent_mode: true, integrate_google_consent_mode: true });

网络推取通知

从 @active-reach/web-sdk/push数字 :

import { AegisWebPush } from '@active-reach/web-sdk/push';

const push = new AegisWebPush({
  writeKey: 'YOUR_WRITE_KEY',
  apiHost: 'https://YOUR_CELL.activereach.ai',
  vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
  contactId: 'user_123',
  organizationId: 'org_456',
  serviceWorkerPath: '/aegis-sw.js',
});

await push.initialize();

复制 dist/aegis-sw.js 给您的 public/ 因此,服务员被服务在根部.

内接通讯和部件

每个应用格式——模式、旗帜、工具提示、全屏接管、底页和交互式部件(平轮、刮卡、核动力源/卫星调查、测验、倒计时、明星评分、民意测验、多步骤表格)——都通过一个系统提供 单一入口数字 : AegisMessageRuntime。 。 。 .

import { AegisMessageRuntime } from '@active-reach/web-sdk';

const runtime = new AegisMessageRuntime({
  writeKey: 'YOUR_WRITE_KEY',
  apiHost: 'https://YOUR_CELL.activereach.ai',
  contactId: 'user_123',     // optional — set once the visitor is known
  organizationId: 'org_456',
  propertyId: 'prop_789',    // the SDK install (website/app) this page is
});

await runtime.initialize();

从旧版本搬走? AegisInAppManager, (中文(简体) ), AegisWidgetManager,以及 AegisPlacementManager 不再成为公共API的一部分—— AegisMessageRuntime 是一个支持的切入点并制作所有格式。 独立的"放置"系统被移除;内置内容现在作为 嵌入式卡片 (见下文).

宣传内容、受众、时间表和频率上限在仪表板上配置了服务器侧(App 个人化) (中文(简体) ). SDK评价客户端触发器(滚动深度,页面上的时间,退出意向,不活动,自定义事件),并自动使匹配运动.

从应用程序驱动触发身份( I)

runtime.track('added_to_cart');         // fire event-based display triggers
runtime.notifyConversion('purchase');   // suppress a campaign after it converts
await runtime.updateContactId('contact_42'); // re-evaluate once the visitor signs in

安置——运动如何惠及客户

每次选一次或多次 发送模式 在仪表板上 安置情况 选项卡。 它们并非相互排斥:

嵌入式卡片(内置入式)

将空元素丢入要显示的牌中 。 内容 data-aegis-slot 价值必须等于运动价值 类别 (单位:千美元)widget_category 在仪表板上。 在加载时, SDK 将填充该类的首个符合条件的运动:

<!-- Renders the active "promo" campaign here, inline in your page -->
<div data-aegis-slot="promo"></div>

没有每个片段的脚本和手动注册—— runtime.initialize() 每张扫描 [data-aegis-slot] 元素并填充。 它在每次SSE/poll刷新上重新扫描,并跳过它已经填充的槽.

槽壳-在运动到来前保留盒子

当它的竞选登陆时,一个空位会增长,这个空位将页面推倒(layout shift),而英雄形象要求等待竞选取来. SDK用一个 外壳: 适当大小的占位符, 绘制到每个空位 在此之前 它收集,然后运动完成。 一个没有东西填补的插槽,一旦得到答案,就会崩溃,所以一个框从不显示,而后消失.

SDK从第一个有1个槽的槽取出每个槽的壳:

1. 内嵌到页面打印形状 (服务器提交的网页): shapes 从 GET /v1/in-app/slot-shapes (下),以脚本标记. 当这个标记出现时,它所缺失的插槽被视作"不会填满".

   <script type="application/json" data-aegis-slot-shapes>{"shapes":[ … ]}</script>
   

2. 槽本身的属性 (任何地点,用手):

   <div data-aegis-slot="hero" data-aegis-slot-aspect="8/3"></div>
   <div data-aegis-slot="commerce" data-aegis-slot-min-height="272"></div>
   

   data-aegis-slot-aspect 带 w/h (或 w:h) (中文(简体) ). data-aegis-slot-min-height 使用像素或 CSS 长度(300, (中文(简体) ), 20rem, (中文(简体) ), 45vh) (中文(简体) ).
3. 上次拜访的形状:每次获取后,SDK会将获胜的竞选形状保存在 localStorage键是属性加所申报的表面、屏幕和出入口(locationId),保存的形状在6小时后失效. 如果存储被屏蔽, 此步骤会被跳过 .

你让自己变成一个人 如果空档已经有子女(a) data-aegis-slot-default 倒计时,或者你自己 <div data-aegis-slot-shell> 孩子,SDK画什么也没有。 它用竞选来取代你的外壳,或者在槽不能填满时去掉外壳,恰好是它自己做的. SDK从不画出标记的形状 may_be_empty (例如,首次访问者可乘回购铁路)。 只有槽的自有属性才能为一个框保留一个框.

GET /v1/in-app/slot-shapes: 用于服务器渲染器. 它使用相同的 写键头与 /v1/in-app/active (单位:千美元)X-Aegis-Write-Key选项 X-User-ID 编号 : X-Contact-ID 编号 : X-Property-Id) (中文(简体) ). 查询参数为: property_id (当信头缺席时使用), surface, (中文(简体) ), screen, (中文(简体) ), page_url (路径+搜索), location_id, (中文(简体) ), device_type, (中文(简体) ), geo 财务报告和审定财务报表 is_new_user反应包括: Cache-Control: private, max-age=60 而身体则 {"shapes": [SlotShape, …]},每个插槽一个形状 将 填满 空出的时间段将无法填补 。 每个运动在 /v1/in-app/active 也带着自己的 slot_shape。 。 。 .

自己打印贝壳的主机. ACS的店面 让他们从 display.inapp_slot_shapes。“ Shopify”主题应用程序扩展名使其来自商店元场 aegis.slot_shapes,单元格保持同步(shopify-plugin/theme-app-extension/snippets/aegis-slot-shell.liquid) (中文(简体) ). 都标出他们的炮弹 data-aegis-slot-shell + 键 data-aegis-shell-owner="host" 并打印出内线形状,所以SDK采用上述形状.

SlotShape数字 :

英雄画出幻灯片 0 为 <img fetchpriority="high" decoding="async" width height> 懒惰地载着其他的滑行。 铁路卡图像携带 decoding="async" 加上明确的 width编号 :height,然后在一次解码后消失.

Cart State——一家商店,以CEP标准方式提供

每个电车反应表面—— 免费交货进度卡,独立 进度栏,车价值 目标设定规则,以及 推车回收 部件 - 读取一车店。 你以同样的方式喂养它 发射 电子商务活动 你已经开火了 SDK是活车 禁止召人作客.

// 1) Wire the ecommerce tracker into the cart store, once at boot:
runtime.bindEcommerce(aegis.ecommerce);

// 2) Fire ecommerce events as the shopper shops — the cart is derived from these:
aegis.ecommerce.addToCart({ product_id: 'p1', name: 'Cap', price: 499, quantity: 1 });
aegis.ecommerce.cartViewed({ value: 998, currency: 'INR', products: [/* … */] }); // authoritative snapshot

平台安装不需要事件线条 - 插件为你做。 钱是 自动检测并输入同一商店:

逃逸舱门 ——无头主机不放出电子商务事件可以推动 直接推车; 这写同一个商店:

runtime.setCartState({ total: 149.99, itemCount: 2, currency: 'INR' });

插件系统

以自定义插件扩展 SDK :

import type { Plugin } from '@active-reach/web-sdk';

const myPlugin: Plugin = {
  name: 'my-plugin',
  version: '1.0.0',

  async init(config) { /* called on SDK init */ },

  async beforeEventCapture(event) {
    // Modify or enrich events before capture
    event.properties = { ...event.properties, enriched: true };
    return event;
  },

  async afterEventCapture(event) {
    // Post-capture logic (external forwarding, logging, etc.)
  },
};

aegis.use(myPlugin);

类型脚本支持

包括完整类型的定义。 扩展类型安全事件跟踪 :

// types/aegis.d.ts
import '@active-reach/web-sdk';

declare module '@active-reach/web-sdk' {
  interface TrackEventProperties {
    'Purchase Completed': {
      order_id: string;
      revenue: number;
      currency: string;
    };
    'Product Viewed': {
      product_id: string;
      product_name: string;
      price: number;
    };
  }
}

饼干和存储

所有饼干 : SameSite=Lax, (中文(简体) ), Secure (只有HTTPS),域范围(可选).

内容安全政策

如果您的网站使用内容安全政策,请添加这些指令:

script-src: 'self' https://platform.active-reach.ai;
connect-src: 'self' https://*.activereach.ai;
style-src: 'self' 'unsafe-inline';
img-src: 'self' https://*.activereach.ai data:;

如果通过CDN使用DOMPurify,也添加:

script-src: https://cdnjs.cloudflare.com;

CSP 缺失时常见错误 : Refused to connect to 'https://...activereach.ai' ——将域添加到 connect-src。 。 。 .

警卫

• 写入密钥: 发布客户端标识符. 无法读取数据或修改服务器状态 。 安全嵌入源代码.
• HTML 卫生: 用途 多维化 当有严格的允许列表时。 返回到仅文本渲染 .
• URL 验证: 所有验证的 URL ─ javascript: 财务报告和审定财务报表 data: 协议被封锁 .
• 同意: 拒绝同意时, 事件被放弃( 不排队) wait_for_consent 已启用.
• 运输:所有API的呼叫都使用HTTPS并带有无记名符号认证.

什么不跟踪

永远不要通过敏感数据作为事件属性 :

// Never do this
aegis.track('Login', { password: '...' });
aegis.identify('user_123', { ssn: '...', credit_card: '...' });

SDK不过滤或编辑属性. 您负责确保所要收集的物品不包括在有效载荷中.

调试

aegis.debug(true);

// Or via init
aegis.init('KEY', { debug: true });

控制台输出 :

[Aegis] Initializing SDK...
[Aegis] Event queued: track { button_name: 'Sign Up' }
[Aegis] Flushing 5 events
[Aegis] Batch sent successfully

子路径导出

浏览器支持

Chrome 80+, Firefox 78+, Safari 14+, Edge 80+.

许可证

麻省理工学院