ConverlayConverlay

API参考

@converlay/sdk 的完整 TypeScript 类型定义。

创建Converlay(配置)

创建 Converlay 跟踪实例的工厂函数。所有状态都处于封闭状态——没有全局副作用。

ConverlayConfig
interface ConverlayConfig {
  /** Your .myshopify.com domain (required). */
  shopDomain: string
  /** Collection endpoint. Default: "https://converlay.app/api/events/collect" */
  endpoint?: string
  /** Send page_view on init. Default: false */
  autoPageView?: boolean
  /** Enable debug logging. Default: false */
  debug?: boolean
  /** Initial consent state. Default: both granted */
  consent?: ConsentInput
}

转换实例

createConverlay() 返回的对象。

ConverlayInstance
interface ConverlayInstance {
  /** Track a named event with optional properties. */
  track: (eventName: string, properties?: TrackProperties) => void
  /** Identify the current user for enhanced matching. */
  identify: (data: IdentifyData) => void
  /** Update consent state. */
  setConsent: (consent: ConsentInput) => void
  /** Force-send any queued events immediately. */
  flush: () => Promise<void>
  /** Cleanup timers and state. */
  destroy: () => void
}

跟踪属性

传递给 track() 的属性。接受任意附加键。

TrackProperties
interface TrackProperties {
  ecommerce?: EcommerceData
  userData?: UserData
  pageType?: string
  [key: string]: unknown
}

识别数据

客户数据传递至 identify()。所有字段都是可选的。

IdentifyData
interface IdentifyData {
  customerId?: string
  email?: string
  phone?: string
  firstName?: string
  lastName?: string
}

同意类型

ConsentInput 是您传递给 SDK 的内容。 ConsentData 是事件负载中包含的有线格式。

ConsentInput & ConsentData
interface ConsentInput {
  analytics?: boolean
  marketing?: boolean
}

interface ConsentData {
  analytics: boolean
  marketing: boolean
  ad_user_data: boolean
  ad_personalization: boolean
}

电商类型

EcommerceData & EcommerceItem
interface EcommerceData {
  transaction_id?: string
  value?: number
  currency?: string
  items?: EcommerceItem[]
  item_list_id?: string
  item_list_name?: string
  search_term?: string
}

interface EcommerceItem {
  item_id: string
  item_name?: string
  item_variant?: string
  price: number
  quantity: number
}

用户数据

用于增强匹配的用户数据。以纯文本形式发送到收集端点,在转发之前在服务端进行哈希处理。

UserData
interface UserData {
  email?: string
  phone?: string
  firstName?: string
  lastName?: string
  city?: string
  state?: string
  country?: string
  postalCode?: string
}

事件负载

发送到收集端点的有线格式有效负载。您不需要直接构建它 - SDK 通过您的 track() 和 identify() 调用来构建它。

EventPayload
interface EventPayload {
  event_id: string
  event_name: string
  shop_domain: string
  page_url: string
  referrer: string
  client_id: string
  session_id: string
  fbp: string
  fbc?: string
  gclid?: string
  ttclid?: string
  fbclid?: string
  utm_source?: string
  utm_medium?: string
  utm_campaign?: string
  utm_term?: string
  utm_content?: string
  customer_id?: string
  page_type?: string
  user_data: WireUserData
  consent_data: ConsentData
  ecommerce: WireEcommerceData | null
  user_agent: string
  sdk_version: string
}