API Reference

Complete TypeScript type definitions for @converlay/sdk.

createConverlay(config)

Factory function that creates a Converlay tracking instance. All state lives in closures — no global side effects.

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
}

ConverlayInstance

The object returned by 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
}

TrackProperties

Properties passed to track(). Accepts arbitrary additional keys.

TrackProperties

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

IdentifyData

Customer data passed to identify(). All fields are optional.

IdentifyData

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

Consent types

ConsentInput is what you pass to the SDK. ConsentData is the wire format included in event payloads.

ConsentInput & ConsentData

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

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

Ecommerce types

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

User data for enhanced matching. Sent in plain text to the collection endpoint, hashed server-side before forwarding.

UserData

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

EventPayload

The wire-format payload sent to the collection endpoint. You don't construct this directly — the SDK builds it from your track() and identify() calls.

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
}

Previous← Integración React