useTracker()

useTracker is the unified tracking entry — it auto-routes to the group WebSDK or the self-hosted channel based on the system/info.tracker config (#228), transparently to business code. Business code / components call useTracker().track(event, payload) to report custom events, never touching window.WebSDK directly — bypassing it loses the framework's gate (auto no-op when config isn't ready) and degradation (lazy-load / fault tolerance), and a raw call throws when config is missing.

How It Works

  1. Dual gate — reporting only happens when both of the following hold; missing either → silent no-op (no error):
    • ModuleOptions.tracker.enabled is truthy (master switch, default true)
    • system/info.tracker has either channel configured: endpoint (self-hosted channel, #228) or appId + encryptedConfig (group WebSDK channel) — see Tracking · reporting channels for behavior and precedence

    This makes the "backend config not ready" case zero-special-handling: component tracking is still written, nothing is sent at runtime, and reporting starts automatically once the backend provides config.
  2. Lazy-load + fault tolerance — on the WebSDK channel the first report triggers SDK lazy-loading; an unready SDK / a single failed event are swallowed (console.error), never interrupting business logic (fire-and-forget). The self-hosted channel never loads WebSDK — events queue in memory and flush in batches (sendBeacon first, fetch keepalive fallback); see Tracking · reporting channels.

Return Value

NameTypeDescription
isEnabled() => booleanWhether tracking is enabled (master switch + backend config both ready)
track(event: WebSdkEvent | (string & {}), payload?: Record<string, unknown>) => voidReport one event (fire-and-forget; silent no-op when not enabled)

event: Preset Enum + Custom Event Names (channel-dependent semantics)

event accepts the WebSdkEvent preset enum (keeps IDE autocomplete) or any custom string. The two reporting channels treat non-enum names differently:

  • Self-hosted channel (system/info.tracker.endpoint): custom event names are passed through and stored as-is (your backend owns the schema) — business events like login / sign_up / favorite / like can be reported directly. Naming convention: snake_case, and don't duplicate a preset enum's meaning.
  • Group WebSDK channel: the SDK only accepts the 28 preset enums below; non-enum names get a dev-time console.warn and are ignored (silent in prod) — the whitelist is the SDK's constraint.

The 28 preset events the SDK actually supports:

CategoryEvents
Page / Navigationnavigation, appPageView, appInstall, pageClick, appPageitemExposure, appPageitemClick
RecommendationrecommendListView, recommendListClick
ContentvideoEvent, novelEvent, comicEvent
SearchkeywordSearch, keywordClick
Ads (self-rendered)advertising, adImpression, adClick
Ads (AdSDK)adRequest, adFill, adNoFill, adLoadSuccess, adImpressionSdk, adClickSdk, adClose, adError
IMimEvent, imConversationView, imConnectionSuccess, imMessageContent

payload fields vary per event and are validated by the SDK's internal schema; the framework keeps a single Record<string, unknown> type rather than refining each event.

Usage Examples

// Example 1: report a page view
const { track } = useTracker()
track('appPageView', { page_key: 'home', page_name: 'Home' })

// Example 2: report a search keyword
function onSearch(keyword: string) {
  track('keywordSearch', { keyword })
}

// Example 3: check enablement before expensive payload prep
const { isEnabled, track } = useTracker()
if (isEnabled()) {
  const payload = buildExpensivePayload()
  track('videoEvent', payload)
}

Caveats

  • Don't call window.WebSDK directly — it bypasses the gate / degradation and throws when config is missing. Always go through useTracker().track().
  • Don't hand-assemble ad tracking fields — use useAdTrack (slot-level + creative-level fields auto-assembled), or just use SwAd* components (built-in impression / click tracking).
  • Reporting is fire-and-forget and returns no Promise; failures only console.error and never affect the business flow.