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.

Method Categories

Category	Methods	Purpose
Initialization	`init()`, `config()`	SDK setup and configuration
User Management	`identify()`, `setUserProperties()`, `setUserLanguage()`, `addTags()`, `setUsersList()`	User identification and properties
Campaign Tracking	`setCampaignParams()`, `linkAdPlatformId()`	UTM and campaign parameters
Event Tracking	`trackEvent()`, `trackSubscription()`, `trackProductView()`, `trackAddToCart()`, `trackRemoveFromCart()`, `trackCheckoutStarted()`, `trackOrderCompleted()`	Analytics and commerce tracking
Push Notifications	`pushRequestPermission()`, `pushMessage()`, `pushStatus()`	Push notification management
Session Management	`startSessionRecording()`, `stopSessionRecording()`	Session recording control
Consent Management	`consent()`	User consent handling
Event System	`on()`	Event callbacks and listeners
Deprecated Methods	Various aliases	Backward compatibility

Initialization

init()

📄 Page Load

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

Signature:

Hood('init', tagId, config?)

Parameters:

Parameter	Type	Required	Description
`tagId`	`string`	✅ Yes	Your HoodEngage tag identifier
`config`	`object`	❌ No	Configuration object with SDK settings

Configuration Options:

Option	Type	Default	Description
`analytics`	`boolean`	`false`	Enable analytics tracking
`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
`disable-autoconf`	`boolean`	`false`	Disable automatic configuration fetch
`no-override`	`boolean`	`false`	Prevent configuration overrides

Example:

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

Info

Manual Configuration Mode

When you provide a config object to init(), the SDK enters manual configuration mode:

Auto-conf is disabled: SDK will NOT fetch configuration from tag_url/<tagId>.json
Complete manual control: You must specify all required settings in the config object
No automatic setup: Features like modals, push notifications, and analytics must be explicitly configured

For detailed manual configuration examples and advanced setups, see Manual Initialization Guide.

Auto-configuration: Only occurs when no config object is provided - SDK automatically fetches configuration from tag_url/<tagId>.json.

config()

📄 Page Load

Purpose: Updates SDK configuration with key-value pairs. Can be called before or after initialization.

Signature:

Hood('config', key, value)

Parameters:

Parameter	Type	Required	Description
`key`	`string`	✅ Yes	Configuration key (case-insensitive)
`value`	`any`	✅ Yes	Configuration value

URL Handling: URLs without scheme are automatically prefixed with https://.

Examples:

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

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

// Set modal theme
Hood('config', 'modals_config', { theme: 'dark' });

Precedence: Configuration set via config() has the highest precedence at runtime.

User Management

identify()

👤 User Behavior

Purpose: Identifies a user with a unique ID and optional traits. Stages user ID for sync on unload or next activity.

Signature:

Hood('identify', userId, traits?)

Parameters:

Parameter	Type	Required	Description
`userId`	`string`	✅ Yes	Unique user identifier
`traits`	`object`	❌ No	User attributes and properties

Example:

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

Sync Behavior: User ID is staged and synced on page unload or next activity to ensure data consistency.

setUserProperties()

👤 User Behavior

Purpose: Attaches user attributes and properties to the current user profile.

Signature:

Hood('setuserproperties', keyOrObject, value?)

Parameters:

Parameter	Type	Required	Description
`keyOrObject`	`string` or `object`	✅ Yes	Property key or object with multiple properties
`value`	`any`	❌ No	Property value (required if keyOrObject is string)

Examples:

// 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()

👤 User Behavior

Purpose: Sets the user’s preferred language using ISO language codes. This language preference is saved to the user profile and used for modal selection when identity matching occurs.

Signature:

Hood('setuserlanguage', languageCode)

Parameters:

Parameter	Type	Required	Description
`languageCode`	`string`	✅ Yes	ISO 639-1 language code (e.g., ’en’, ’es’, ‘fr’)

Examples:

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

Key Features:

Profile Storage: Language preference is saved to the user profile
Identity Matching: When user is identified, their language preference is retrieved
Modal Selection: The saved language is used to select appropriate modal templates
Cross-Session: Language preference persists across browser sessions

Use Cases:

User selects language in settings → setuserlanguage('es') → Spanish modals shown
Multi-language websites → Detect browser language → Set user preference
A/B testing → Different language versions of modals

Supported Codes: Standard ISO 639-1 two-letter language codes.

addTags()

👤 User Behavior

Purpose: Adds tags to the user profile for categorization and segmentation.

Signature:

Hood('addtags', tags)

Parameters:

Parameter	Type	Required	Description
`tags`	`array`	✅ Yes	Array of tag strings

Example:

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

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

setUsersList()

👤 User Behavior

Purpose: Sets a list of users for tracking and analytics purposes.

Signature:

Hood('setuserslist', userList)

Parameters:

Parameter	Type	Required	Description
`userList`	`array`	✅ Yes	Array of user identifiers

Example:

Hood('setuserslist', ['user_1', 'user_2', 'user_3']);

Use Cases: Bulk user operations, list-based targeting, analytics grouping.

Campaign Tracking

setCampaignParams()

🖱️ Interaction

Purpose: Stores UTM and campaign parameters for tracking marketing campaigns.

Signature:

Hood('setcampaignparams', campaignData)

Parameters:

Parameter	Type	Required	Description
`campaignData`	`object`	✅ Yes	Object containing campaign parameters

Campaign Parameters:

Parameter	Type	Description
`utm_source`	`string`	Traffic source (e.g., ‘google’, ‘facebook’)
`utm_medium`	`string`	Marketing medium (e.g., ‘cpc’, ’email’)
`utm_campaign`	`string`	Campaign name
`utm_term`	`string`	Paid search keywords
`utm_content`	`string`	Ad content identifier

Example:

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

Inclusion: Campaign data is automatically included in subsequent activity payloads.

linkAdPlatformId()

🖱️ Interaction

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

Signature:

Hood('linkadplatformid', platformId, value)

Parameters:

Parameter	Type	Required	Description
`platformId`	`string`	✅ Yes	Advertising platform identifier
`value`	`string`	✅ Yes	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

trackEvent()

🖱️ Interaction

Purpose: Tracks custom events with optional payload data.

Signature:

Hood('trackevent', eventName, payload?)

Parameters:

Parameter	Type	Required	Description
`eventName`	`string`	✅ Yes	Name of the event to track
`payload`	`object`	❌ No	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.

trackSubscription()

🖱️ Interaction

Purpose: Tracks subscription events with type-specific data.

Signature:

Hood('tracksubscription', type, data)

Parameters:

Parameter	Type	Required	Description
`type`	`string`	✅ Yes	Subscription type (e.g., ‘S_PUSH’)
`data`	`object`	✅ Yes	Subscription-specific data

Example:

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

Code Mapping: Uses predefined code mappings for different subscription types.

Commerce Tracking Methods

trackProductView()

🖱️ Interaction

Purpose: Tracks when a user views a product.

Signature:

Hood('trackproductview', product)

Parameters:

Parameter	Type	Required	Description
`product`	`object`	✅ Yes	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()

🖱️ Interaction

Purpose: Tracks when a user adds a product to their cart.

Signature:

Hood('trackaddtocart', product)

Parameters:

Parameter	Type	Required	Description
`product`	`object`	✅ Yes	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()

🖱️ Interaction

Purpose: Tracks when a user removes a product from their cart.

Signature:

Hood('trackremovefromcart', product)

Parameters:

Parameter	Type	Required	Description
`product`	`object`	✅ Yes	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()

🖱️ Interaction

Purpose: Tracks when a user starts the checkout process.

Signature:

Hood('trackcheckoutstarted')

Example:

Hood('trackcheckoutstarted');

Event Code: Emits SHOP activity with message store_checkout.

trackOrderCompleted()

🖱️ Interaction

Purpose: Tracks when a user completes an order.

Signature:

Hood('trackordercompleted')

Example:

Hood('trackordercompleted');

Event Code: Emits SHOP activity with message store_completed.

Push Notifications

pushRequestPermission()

🔧 Custom

Purpose: Requests push notification permission from the user.

Signature:

Hood('pushrequestpermission', callback?)

Parameters:

Parameter	Type	Required	Description
`callback`	`function`	❌ No	Callback function when native prompt shows

Example:

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

Events: Emits reqPushPrompt event and adds callback to onPushShow event.

pushMessage()

🔧 Custom

Purpose: Displays a push notification message via Service Worker.

Signature:

Hood('pushmessage', message, callback?)

Parameters:

Parameter	Type	Required	Description
`message`	`object`	✅ Yes	Notification message object
`callback`	`function`	❌ No	Callback function after showing notification

Message Object:

Property	Type	Description
`title`	`string`	Notification title
`options`	`object`	Notification options (body, icon, etc.)

Example:

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

pushStatus()

🔧 Custom

Purpose: Gets the current push notification permission status.

Signature:

Hood('pushstatus', callback)

Parameters:

Parameter	Type	Required	Description
`callback`	`function`	✅ Yes	Callback function to receive status

Example:

Hood('pushstatus', function(status) {
  console.log('Push status:', status);
  // Possible values: 'granted', 'denied', 'default'
});

Events: Subscribes to getPushStatus event.

Session Management

startSessionRecording()

⏰ Time-based

Purpose: Starts session recording for user behavior analysis.

Signature:

Hood('startsessionrecording')

Example:

Hood('startsessionrecording');

Note: Currently logs to console. Full implementation may vary by configuration.

stopSessionRecording()

⏰ Time-based

Purpose: Stops session recording.

Signature:

Hood('stopsessionrecording')

Example:

Hood('stopsessionrecording');

Note: Currently logs to console. Full implementation may vary by configuration.

👤 User Behavior

Purpose: Sets user consent for data collection and analytics.

Signature:

Hood('consent', consentData)

Parameters:

Parameter	Type	Required	Description
`consentData`	`boolean` or `object`	✅ Yes	Consent flag or consent object

Consent Object:

Property	Type	Description
`analytics`	`boolean`	Allow analytics tracking

Examples:

// Simple boolean consent
Hood('consent', true);

// Detailed consent object
Hood('consent', {
  analytics: true,
  marketing: false,
  personalization: true
});

Effect: When analytics is true, analytics tracking is allowed to run.

Event System

on

⚙️ Advanced

Purpose: Registers event callbacks for internal SDK events.

Signature:

Hood('on', eventName, callback, options?)

Parameters:

Parameter	Type	Required	Description
`eventName`	`string`	✅ Yes	Name of the event to listen for
`callback`	`function`	✅ Yes	Callback function to execute
`options`	`object`	❌ No	Optional parameters for the event

Available Events:

Event	Description
`onPushGranted`	Push permission granted
`onPushBlocked`	Push permission blocked
`onPushShow`	Push prompt shown
`autoconfReady`	Auto-configuration completed

Example:

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

Hood('on', 'autoconfReady', function(config) {
  console.log('SDK configured:', config);
});

Deprecated Methods

Info

Deprecated Methods

The following methods are deprecated but maintained for backward compatibility. Use the recommended alternatives instead.

Deprecated Method	Recommended Alternative	Description
`requestpushpermission`	`pushrequestpermission`	Request push permission
`showpushmessage`	`pushmessage`	Show push message
`utm`	`setcampaignparams`	Set UTM parameters
`setuserid`	`identify`	Identify user
`setpartnerid`	`linkadplatformid`	Link ad platform ID
`track`	`setuserproperties`	Set user properties
`getpushstatus`	`pushstatus`	Get push status

Migration Example:

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

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

Best Practices

Method Call Order

Methods are processed in a specific order for optimal performance:

Configuration: config, init
User Management: identify, setuserproperties, setuserlanguage
Campaign Tracking: setcampaignparams, linkadplatformid
Event Tracking: trackevent, tracksubscription, commerce methods
Push Notifications: pushrequestpermission, pushmessage, pushstatus
Session Management: startsessionrecording, stopsessionrecording
Consent: consent
Event System: on

Error Handling

try {
  Hood('trackevent', 'button_click', { button: 'signup' });
} catch (error) {
  console.error('Tracking error:', error);
}

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:

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

// Identify user
Hood('identify', '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

Info

Method Names are Case-Insensitive

All Hood Web SDK method names are case-insensitive. This means you can use any combination of uppercase and lowercase letters, and the SDK will execute the method correctly.

Examples of valid calls:

// 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' });

Why camelCase in documentation?

Readability: setUserProperties() is more readable than setuserproperties
Clarity: trackAddToCart() clearly shows it’s about adding to cart
Consistency: Follows common JavaScript naming conventions
Functionality: All variations work identically in practice

Best Practice: Use the camelCase format shown in this documentation for readability and consistency, but don’t worry if you accidentally use different casing - it will still work!

LinkedIn Facebook Instagram

Web SDK Reference

Web SDK Reference

Method Categories

Initialization

init()

config()

User Management

identify()

setUserProperties()

setUserLanguage()

addTags()

setUsersList()

Campaign Tracking

setCampaignParams()

linkAdPlatformId()

Event Tracking

trackEvent()

trackSubscription()

Commerce Tracking Methods

trackProductView()

trackAddToCart()

trackRemoveFromCart()

trackCheckoutStarted()

trackOrderCompleted()

Push Notifications

pushRequestPermission()

pushMessage()

pushStatus()

Session Management

startSessionRecording()

stopSessionRecording()

Consent Management

consent

Event System

on

Deprecated Methods

Best Practices

Method Call Order

Error Handling

Performance Considerations

Common Patterns

Important Notes