Web SDK Reference

Complete API reference for the Hood Web SDK (ht.js), version 25.8.20, aligned with the latest public API.

Overview

The SDK exposes a single global function (by default Hood) that accepts method calls in the form:

Hood(methodName, ...args)

You can also configure initial behavior via the <script> tag attributes (e.g., data-activity_url, data-amp).

Initialization

Script include

<script
  src="/sdk/ht.js"
  data-tag="YOUR_TAG_ID"
  data-analytics="1"
  data-activity_url="https://dev-t.ocmhood.com/v3/activity"
  data-modal_url="https://dev-cdn.ocmtag.com/modals/"
  data-tag_url="https://dev-cdn.ocmtag.com/tag/">
</script>

The loader reads data-* attributes into config (lowercased keys). For URLs, values without a scheme are coerced to https://.

Auto configuration

If no config is provided programmatically, the SDK fetches tag_url/<tag>.json based on data-tag.

API Methods

Hood(‘init’, token, cfg)

Initializes the SDK, sets the tag token, and applies configuration. Triggers auto-config if cfg is not provided (unless disable-autoconf is set).

Hood('init', 'YOUR_TAG_ID', {
  analytics: true,
  activity_url: 'https://dev-t.ocmhood.com/v3/activity',
  crashlytics: false,
  modals_config: { /* ... */ },
  push_config: { key: 'VAPID_PUBLIC_KEY', service_worker_path: '/sw-latest.js' }
})

Real-world: Call as early as possible to ensure consent, analytics, modals, and push are registered before user interaction.

Signature

Hood('init', token: string, cfg?: object): void

Parameters

• token (string, required): Tag identifier.
• cfg (object, optional): Selected keys: analytics, activity_url, analytics_url, crashlytics_url, subscription_url, modal_url, tag_url, modals_config, tag_config, push_config, disable-autoconf, no-override.

Returns

• void

Errors

• Network/config fetch failures are logged; see Error Codes.

Related

• config, consent, pushrequestpermission

Hood(‘config’, key, value)

Sets a config key at runtime. Keys ending with _url are normalized to absolute HTTPS if missing scheme.

Hood('config', 'activity_url', 'https://dev-t.ocmhood.com/v3/activity')
Hood('config', 'analytics', true)

Signature

Hood('config', key: string, value: any): void

Parameters

• key (string, required)
• value (any, required)

Returns

• void

Hood(‘consent’, consent)

Sets consent. Accepts boolean for analytics or full object.

Hood('consent', true) // enable analytics only
Hood('consent', { analytics: true, functional: true, advertising: false })

Real-world: Persist a user’s cookie banner choice; SDK stores it and emits a userConsent event internally.

Signature

Hood('consent', consent: boolean|object): void

Parameters

• consent (boolean|object, required)

Returns

• void

Hood(‘on’, event, callback)

Registers a callback for SDK events.

Hood('on', 'autoconfReady', (config) => console.log('Ready', config))
Hood('on', 'getPushStatus', (status) => console.log('Push status', status))
Hood('on', 'onPushShow', () => console.log('Native prompt shown'))

Common events: autoconfReady, getPushStatus, onPushShow, onPushClosed, onPushBlocked, onPushGranted.

Signature

Hood('on', event: string, callback: Function): void

Parameters

• event (string, required)
• callback (function, required)

Returns

• void

Hood(‘identify’, userId, traits?)

Sets the current user id and optional traits for syncing.

Hood('identify', 'user-123', { plan: 'pro', email: '[email protected]' })

Real-world: Call after login to bind events to a known user.

Signature

Hood('identify', userId: string, traits?: object): void

Parameters

• userId (string, required)
• traits (object, optional)

Returns

• void

Hood(‘setuserproperties’, props)

Sets arbitrary user properties for future sync.

Hood('setuserproperties', { country: 'DE', newsletter: true })

Signature

Hood('setuserproperties', properties: object): void

Parameters

• properties (object, required)

Returns

• void

Hood(‘setuserlanguage’, langCode)

Sets preferred language. Must be a supported base code (e.g., en, de, fr). Returns false if invalid.

Hood('setuserlanguage', 'de')

Signature

Hood('setuserlanguage', langCode: string): boolean

Parameters

• langCode (string, required): Supported base code (e.g., en, de, fr).

Returns

• boolean (false if unsupported)

Hood(’linkadplatformid’, key, value)

Adds a partner/ad-platform id for retargeting.

Hood('linkadplatformid', 'fbclid', 'XYZ')

Signature

Hood('linkadplatformid', key: string, value: string): void

Hood(‘addtags’, tags)

Adds user tags for segmentation.

Hood('addtags', ['vip', 'beta'])

Signature

Hood('addtags', tags: any): void

Hood(‘setuserslist’, list)

Associates the user with list(s) for audience targeting.

Hood('setuserslist', ['buyers-q3'])

Signature

Hood('setuserslist', list: any): void

Hood(’trackevent’, name, payload?)

Tracks a custom business event.

Hood('trackevent', 'signup_completed', { source: 'landing_a' })

Signature

Hood('trackevent', name: string, payload?: object): void

Hood(’tracksubscription’, type, data)

Tracks a subscription-type action (maps to S_* codes).

Hood('tracksubscription', 'email', { address: '[email protected]' })
Hood('tracksubscription', 'push', { endpoint: '...' })

Signature

Hood('tracksubscription', type: string, data: any): void

Commerce helpers

• Hood(’trackproductview’, product) {#hoodtrackproductview}
• Hood(’trackaddtocart’, product) {#hoodtrackaddtocart}
• Hood(’trackremovefromcart’, product) {#hoodtrackremovefromcart}
• Hood(’trackcheckoutstarted’) {#hoodtrackcheckoutstarted}
• Hood(’trackordercompleted’) {#hoodtrackordercompleted}

Hood('trackproductview', { id: 'sku_1', price: 29.9 })
Hood('trackaddtocart', { id: 'sku_1', qty: 2 })
Hood('trackcheckoutstarted')
Hood('trackordercompleted')

Signatures

Hood('trackproductview', product: object): void
Hood('trackaddtocart', product: object): void
Hood('trackremovefromcart', product: object): void
Hood('trackcheckoutstarted'): void
Hood('trackordercompleted'): void

Push utilities

Hood(‘pushrequestpermission’, cb?)

Requests native browser notification permission. Optional callback runs when the prompt is shown.

Hood('pushrequestpermission', () => console.log('Prompt displayed'))

Hood(‘pushmessage’, notification, cb?)

Queues a client-side notification via the registered Service Worker when available.

Hood('pushmessage', { title: 'Welcome', options: { body: 'Thanks for subscribing!' } })

Hood(‘pushstatus’, cb)

Registers a callback that receives the current push permission status: prompt, closed, granted, denied, auto-block, close-block.

Hood('pushstatus', (status) => console.log('Push:', status))

Signatures

Hood('pushrequestpermission', cb?: Function): void
Hood('pushmessage', notification: { title: string, options?: object }, cb?: Function): void
Hood('pushstatus', cb: Function): void

Configuration keys (selected)

• analytics (boolean): Enable analytics events.
• activity_url, analytics_url, crashlytics_url, subscription_url (string): Backend endpoints.
• modal_url, tag_url (string): CDN roots for templates and tag autoconfig.
• modals_config (object): Modal definitions and triggers.
• tag_config (object): DOM tag actions and triggers.
• push_config (object): { key: <VAPID_PUBLIC_KEY>, service_worker_path?: '/sw.js', push_serviceworker?: '/sw.js' }.

Real-world SW setup:

Hood('init', 'YOUR_TAG_ID', {
  push_config: { key: 'VAPID_PUBLIC_KEY', service_worker_path: '/sw.js' }
})

Events

Register with Hood('on', event, callback):

• autoconfReady — configuration finished; receives final CONFIG.
• getPushStatus — emits current push status (prompt, closed, granted, denied, auto-block, close-block).
• onPushShow — native prompt shown.
• onPushClosed — user closed prompt window.
• onPushBlocked — permission denied.
• onPushGranted — permission granted (SDK will proceed to subscription flow).
• PushAllow — emitted when subscription object is captured after permission.

Example:

Hood('on', 'autoconfReady', (cfg) => console.log('Config ready', cfg))
Hood('on', 'getPushStatus', (s) => console.log('Push status', s))

Notes and deprecations

• Legacy aliases (kept for compatibility):
  • requestpushpermission → pushrequestpermission
  • showpushmessage → pushmessage
  • utm → setcampaignparams
  • setuserid → identify
  • setpartnerid → linkadplatformid
  • track → setuserproperties
  • getpushstatus → pushstatus

Troubleshooting

• Service Worker path must be same-origin and served over HTTPS.
• For Safari Web Push on macOS, follow platform-specific steps (see Setup section).
• If auto-config doesn’t load, verify data-tag and data-tag_url are correct and accessible via CORS.

See also: Error Codes • Browser Compatibility • Use Cases

Modals overview

When modals_config is provided, modal definitions are registered and displayed based on triggers (visibility, scroll, timer, event). Each modal defines template (fetched from modal_url) and accessibility/animation options. Closing reasons tracked: click outside (oc), esc, CTA (cta), auto close (ac).

Real-world:

Hood('init', 'TAG', {
  modal_url: 'https://dev-cdn.ocmtag.com/modals/',
  modals_config: {
    modals: [
      {
        id: 'hello',
        template: 'welcome',
        options: { animation: 'fade-in', close_esc: true },
        triggers: [{ type: 'timer', config: { time: 2000 } }]
      }
    ]
  }
})

Tags overview

When tag_config is provided, DOM actions are registered as rules with triggers and optional filters. Each tag:

• i — element selector (e.g., #banner)
• a — action (append, prepend, html, remove, …)
• c — content template (supports {{var.*}}, {{data.*}}, etc.)

Hood('init', 'TAG', {
  tag_config: {
    tags: {
      banner: { i: '#banner', a: 'html', c: '<strong>{{data.user_id}}</strong>' }
    }
  }
})