Web SDK Reference

Web SDK Reference

All methods are invoked via the global function Hood(method, ...args). This reference covers all available methods, their parameters, return values, and practical examples.

Initialization

SDK setup and configuration.

init()

Initializes the Hood Web SDK with a tag ID and optional configuration.

Signature:

Hood('init', tagId, config?)

Parameters:

• tagId (string, required): Your HoodEngage tag identifier
• config (object, optional): Configuration object with SDK settings

Configuration Options:

• analytics (boolean, default: false): When true, also register the pageView and click analytics triggers. The load and beforeunload beacons still send either way — see the note below
• crashlytics (boolean, default: false): Register the crashlytics reporter
• consent (boolean or object): A truthy value is applied as soon as the configuration is processed. An object is passed through; true grants all four categories. From the page, use consent
• activity_url (string): Custom activity endpoint URL
• analytics_url (string): Custom analytics endpoint URL
• crashlytics_url (string): Custom crashlytics endpoint URL
• subscription_url (string): Custom subscription endpoint URL
• modal_url (string): Custom modal assets URL
• tag_url (string): Custom tag configuration URL
• modals_config (object): Modal configuration settings
• tag_config (object): Tag execution configuration
• push_config (object): Push notification configuration
• variables (object): Filter context registered with the filter engine, so tag and modal conditions can reference these values
• function (string, default: 'Hood'): Global function name the SDK installs itself under
• disable-autoconf (boolean, default: false): Disable automatic configuration fetch. Only matters when init is called without a config object (or when set earlier via Hood('config', 'disable-autoconf', true) / a data attribute). Passing any config object already skips autoconf.
• no-override (boolean, default: false): Skip a key that already has a truthy value — false, 0, and '' are still overwritten. See the warning under config(), because the built-in defaults count as values.

Example:

Hood('init', 'YOUR_TAG_ID', {
  analytics: true,
  activity_url: 'https://your-domain.com/v3/activity',
  push_config: {
    key: 'VAPID_PUBLIC_KEY',
    service_worker_path: '/sw-latest.js',
  },
});

config()

Updates SDK configuration with key-value pairs. Only useful before initialization — see the precedence note below.

Signature:

Hood('config', key, value);

Parameters:

• key (string, required): Configuration key (case-insensitive, stored lowercased)
• value (any, required): Configuration value

URL Handling: Keys ending in _url are forced to HTTPS — a bare domain gets an https:// prefix and http:// is upgraded. Other keys are stored as given.

// Set analytics URL
Hood('config', 'analytics_url', 'https://analytics.example.com');

// Enable analytics
Hood('config', 'analytics', true);

// Disable autoconf before init
Hood('config', 'disable-autoconf', true);

Precedence: config() does not win over the fetched configuration. When auto-conf or an init config object is applied, its keys overwrite whatever config() set earlier.

User Management

User identification and properties

identity()

Identifies a user with a unique ID and optional traits.

Signature:

Hood('identity', userId, traits?)

Parameters:

• userId (string, required): Unique user identifier
• traits (object, optional): User attributes and properties

Example:

Hood('identity', 'user_123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'premium',
  signup_date: '2024-01-15',
});

Sets user_id (and optional traits) on the in-memory user profile (md.data / protectedData.u). Those fields are included on the next activity payload and on the unload SYNC beacon. The unload beacon is always sent when analytics’ beforeunload handler runs; it is not gated on whether identity() was called.

setUserProperties()

Attaches user attributes and properties to the current user profile.

Signature:

Hood('setuserproperties', keyOrObject, value?)

Parameters:

• keyOrObject (string or object, required): Property key or object with multiple properties
• value (any, optional): Property value (required if keyOrObject is string)

// Set single property
Hood('setuserproperties', 'subscription_tier', 'premium');

// Set multiple properties
Hood('setuserproperties', {
  subscription_tier: 'premium',
  last_login: '2024-01-20',
  preferred_language: 'en',
  total_purchases: 5,
});

Use Cases: User segmentation, personalization, analytics tracking.

setUserLanguage()

Overrides the language the SDK uses when picking a modal template.

Signature:

Hood('setuserlanguage', languageCode);

Parameters:

• languageCode (string, required): Supported base language code (usually ISO 639-1, e.g. 'en', 'es', 'pt'). Pass the base code only ('pt'). The list includes fil alongside tl.

Hood('setuserlanguage', 'en'); // English
Hood('setuserlanguage', 'es'); // Spanish
Hood('setuserlanguage', 'fr'); // French
Hood('setuserlanguage', 'de'); // German

Effect: The value is held in memory for the current page (BW_INFO.ul) and takes priority when the SDK builds the modal template URL.

Resolution order: Hood('setuserlanguage') override (BW_INFO.ul), then the browser’s preferred language from navigator.languages (base ISO code, first supported match), then 'en'.

If that language is not in the modal’s ml list and sl is true, the modal is not shown. If sl is false, the SDK uses 'en' when present in ml, otherwise the first entry in ml.

An unsupported code leaves the previous value in effect.

Use Cases:

• User selects language in settings → setuserlanguage('es') → Spanish modal templates
• Multi-language sites where the site language differs from the browser language

addTags()

Sets the tag set reported for the current visitor, for categorization and segmentation.

Signature:

Hood('addtags', tags);

Parameters:

• tags (array, required): Array of tag strings

Example:

Hood('addtags', ['vip', 'beta-tester', 'newsletter-subscriber']);

The value is attached to every beacon sent after the call. A falsy value leaves the previous value untouched.

Use Cases: User categorization, campaign targeting, behavioral segmentation.

Hood('addtags', ['vip']);
Hood('addtags', ['beta-tester']);
// reported tags are ['beta-tester'] — 'vip' is gone

Hood('addtags', ['vip', 'beta-tester']);

setUsersList()

Assigns the current visitor to one or more audience lists.

Signature:

Hood('setuserslist', lists);

Parameters:

• lists (array, required): List identifiers this visitor belongs to

Example:

Hood('setuserslist', ['newsletter_q4', 'high_intent']);

The value is attached to every beacon sent after the call. A falsy value leaves the existing lists untouched.

Use Cases: List-based targeting and segmentation of the current visitor.

Campaign Tracking

UTM and campaign parameters

setCampaignParams()

Stores UTM and campaign parameters for tracking marketing campaigns.

Signature:

Hood('setcampaignparams', campaignData);
Hood('setcampaignparams', key, value);

Parameters:

• campaignData (object): Object containing campaign parameters, or
• key (string) and value (string): A single campaign parameter

Campaign Parameters:

Example:

// Object form
Hood('setcampaignparams', {
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'q4-promotion',
  utm_term: 'web analytics',
  utm_content: 'banner-ad-1',
});

// Single-pair form
Hood('setcampaignparams', 'utm_source', 'google');

// The utm_ prefix is optional — this is the same as the line above
Hood('setcampaignparams', 'source', 'google');

Key handling: A key without the utm_ prefix is prefixed automatically, so source and utm_source are equivalent — in the object form too. Keys and values must be strings. The SDK adds utm_ht (the tag ID) on the beacon itself.

Inclusion: Campaign data is included in subsequent activity payloads.

linkAdPlatformId()

Links the user’s advertising platform ID for cross-platform tracking.

Signature:

Hood('linkadplatformid', platformId, value);

Parameters:

• platformId (string, required): Advertising platform identifier
• value (string, required): Platform-specific user ID

Example:

Hood('linkadplatformid', 'facebook', 'fb_user_123');
Hood('linkadplatformid', 'google', 'ga_user_456');

Use Cases: Cross-platform user tracking, advertising attribution, retargeting.

Event Tracking

Analytics and commerce tracking

trackEvent()

Tracks custom events with optional payload data.

Signature:

Hood('trackevent', eventName, payload?)

Parameters:

• eventName (string, required): Name of the event to track
• payload (object, optional): Additional event data

Example:

Hood('trackevent', 'button_clicked', {
  button_name: 'signup',
  page_url: '/homepage',
  user_type: 'new',
});

Hood('trackevent', 'video_watched', {
  video_id: 'intro_video',
  duration: 120,
  completion_rate: 0.8,
});

Event Code: Custom events are tracked with code EVENT. Also fires matching tag/modal event triggers internally via queue.fireNamedEvent(eventName, payload) (no window dispatch, so it will not collide with the host page’s listeners).

trackSubscription()

Tracks subscription events with type-specific data.

Signature:

Hood('tracksubscription', type, data);

Parameters:

• type (string, required): Subscription channel — push, email, phone, or form (case-insensitive)
• data (object, required): Subscription-specific data

Example:

Hood('tracksubscription', 'push', {
  subscription_id: 'sub_123',
  plan: 'premium',
  status: 'active',
});

Code Mapping: The SDK uppercases the type and prefixes it with S_, so 'push' becomes S_PUSH. Pass the bare channel name.

Commerce Tracking Methods

trackProductView()

Tracks when a user views a product.

Signature:

Hood('trackproductview', product);

Parameters:

• product (object, required): Product details

Example:

Hood('trackproductview', {
  product_id: 'prod_123',
  name: 'Wireless Headphones',
  category: 'Electronics',
  price: 99.99,
  currency: 'USD',
});

Event Code: Emits SHOP activity with message store_product_view.

trackAddToCart()

Tracks when a user adds a product to their cart.

Signature:

Hood('trackaddtocart', product);

Parameters:

• product (object, required): Product details

Example:

Hood('trackaddtocart', {
  product_id: 'prod_123',
  name: 'Wireless Headphones',
  price: 99.99,
  quantity: 1,
  currency: 'USD',
});

Event Code: Emits SHOP activity with message store_add_to_cart.

trackRemoveFromCart()

Tracks when a user removes a product from their cart.

Signature:

Hood('trackremovefromcart', product);

Parameters:

• product (object, required): Product details

Example:

Hood('trackremovefromcart', {
  product_id: 'prod_123',
  name: 'Wireless Headphones',
  price: 99.99,
  quantity: 1,
  currency: 'USD',
});

Event Code: Emits SHOP activity with message store_remove_from_cart.

trackCheckoutStarted()

Tracks when a user starts the checkout process.

Signature:

Hood('trackcheckoutstarted');

Example:

Hood('trackcheckoutstarted');

Event Code: Emits SHOP activity with message store_checkout.

trackOrderCompleted()

Tracks when a user completes an order.

Signature:

Hood('trackordercompleted');

Example:

Hood('trackordercompleted');

Event Code: Emits SHOP activity with message store_completed.

Push Notifications

Push notification management

pushRequestPermission()

Requests push notification permission from the user.

Signature:

Hood('pushrequestpermission', callback?)

Parameters:

• callback (function, optional): Callback function when native prompt shows

Example:

Hood('pushrequestpermission', function () {
  console.log('Permission prompt shown');
});

If a callback is passed, it is registered on onPushShow before the native permission prompt is requested. Requires push_config with a VAPID key.

pushMessage()

Queues a push notification message for display via the Service Worker.

Signature:

Hood('pushmessage', message, callback?)

Parameters:

• message (object, required): Notification message object
• callback (function, optional): Called with true once the notification has actually been shown

Message Object:

Example:

Hood(
  'pushmessage',
  {
    title: 'Welcome!',
    options: {
      body: 'Thanks for subscribing to our newsletter',
      icon: '/icon.png',
      badge: '/badge.png',
    },
  },
  function () {
    console.log('Notification shown');
  },
);

Display behavior: Shown when push permission is 'granted'. Until then it is queued in memory for this page load. Requires push_config with a VAPID key.

pushStatus()

Registers a one-shot listener for the push permission status emitted during push initialization (pageReady() after getPermission()).

Signature:

Hood('pushstatus', callback);

Parameters:

• callback (function, required): Called with the status when getPushStatus is emitted

Example:

Hood('pushstatus', function (status) {
  console.log('Push status:', status);
  // Possible values: 'granted', 'denied', 'closed', 'prompt', 'auto-block', 'close-block'
});

Register it from the pre-init HoodEngage queue (or otherwise before push init finishes). Possible values: 'granted', 'denied', 'closed', 'prompt', 'auto-block', 'close-block'. For later outcomes, use Hood('on', 'onPushGranted'|…).

Consent Management

User consent handling

consent

Sets user consent for data collection and analytics.

Signature:

Hood('consent', consentData);

Parameters:

• consentData (boolean or object, required): Consent flag or consent object

Consent Object:

// Simple boolean consent — sets all four categories at once
Hood('consent', true);

// Granular consent object
Hood('consent', {
  analytics: true,
  advertising: false,
  functional: true,
  consent: true,
});

Effect: When analytics is true, analytics tracking is allowed to run and the visitor ID is persisted in localStorage. Revoking analytics clears the persisted visitor id and stored campaign params; the session id stays in sessionStorage.

Persistence: The consent object is persisted in localStorage (userConsent) and is read back on subsequent visits, so a decision does not have to be repeated on every page. A change also emits a consent beacon that records the new state, along with the TCF consent string when a TCF CMP is present.

A truthy consent key on init or auto-conf applies the same way — see init(). Pass real booleans for each category.

Event System

Event callbacks and listeners

on

Registers event callbacks for internal SDK events.

Signature:

Hood('on', eventName, callback);

Parameters:

• eventName (string, required): Name of the event to listen for (case-insensitive)
• callback (function, required): Callback function to execute

Registering the same function twice for one event is a no-op, so callbacks are never invoked twice.

Available Events:

Example:

Hood('on', 'onPushGranted', function () {
  console.log('Push permission granted!');
});

Hood('on', 'PushAllow', function (subscription, finish) {
  // Optional: enrich the visitor before the subscription is uploaded
  Hood('identity', 'user_123');
  finish(); // required — release the upload
});

Deprecated Methods

Backward compatibility

// Old (deprecated)
Hood('utm', { utm_source: 'google' });
Hood('identify', 'user_123');
// or: Hood('setuserid', 'user_123');

// New (recommended)
Hood('setcampaignparams', { utm_source: 'google' });
Hood('identity', 'user_123');

Best Practices

Method Call Order

Calls queued in HoodEngage before the SDK loads are not executed in the order you wrote them. They are sorted into a fixed internal order, and calls of equal rank keep their relative position. The order is:

1. config
2. setcampaignparams
3. identity
4. consent
5. setuserproperties, setuserlanguage
6. linkadplatformid
7. addtags
8. setuserslist
9. on
10. init
11. trackevent, tracksubscription, then the commerce methods
12. pushrequestpermission, pushmessage, pushstatus
13. Deprecated aliases, in this order: requestpushpermission, showpushmessage, utm, identify, setuserid, setpartnerid, track, getpushstatus

Only config and init run before initialization completes. Everything else is deferred until the configuration is ready, which is why a queued on cannot observe autoconfReady.

Error Handling

SDK methods do not throw to the page. Failures go to the internal error-reporting stream. Confirm integrations by inspecting outgoing network requests.

Performance Considerations

• Call init() as early as possible in your application lifecycle
• Use config() to set up configuration before initialization
• Batch user properties updates when possible
• Handle push permission requests gracefully

Common Patterns

Complete User Setup:

This sequence of direct calls works because init is given a config object, which skips the asynchronous auto-conf fetch and makes the SDK ready before the next line runs. Without a config object, the calls that follow init would land in the auto-conf window and be dropped — use the command queue instead.

// Initialize SDK
Hood('init', 'YOUR_TAG_ID', {
  analytics: true,
  push_config: { key: 'VAPID_KEY' },
});

// Set user identity
Hood('identity', 'user_123', {
  email: '[email protected]',
  name: 'John Doe',
});

// Set additional properties
Hood('setuserproperties', {
  subscription_tier: 'premium',
  signup_date: '2024-01-15',
});

// Track events
Hood('trackevent', 'page_viewed', {
  page: '/dashboard',
  user_type: 'premium',
});

E-commerce Tracking:

// Product view
Hood('trackProductView', {
  product_id: 'prod_123',
  name: 'Product Name',
  price: 99.99,
  currency: 'USD',
});

// Add to cart
Hood('trackAddToCart', {
  product_id: 'prod_123',
  quantity: 1,
  price: 99.99,
});

// Checkout
Hood('trackCheckoutStarted');

// Order completion
Hood('trackOrderCompleted');

Important Notes

// All of these work identically:
Hood('init', 'TAG_ID');
Hood('INIT', 'TAG_ID');
Hood('Init', 'TAG_ID');
Hood('iNiT', 'TAG_ID');

Hood('setUserProperties', { name: 'John' });
Hood('SETUSERPROPERTIES', { name: 'John' });
Hood('SetUserProperties', { name: 'John' });
Hood('sEtUsErPrOpErTiEs', { name: 'John' });