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): 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, default: false): Disable automatic configuration fetch
• no-override (boolean, default: 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'
  }
});

config()

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

Signature:

Hood('config', key, value)

Parameters:

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

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

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

User identification and properties

identify()

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:

• userId (string, required): Unique user identifier
• traits (object, optional): 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()

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

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:

• languageCode (string, required): ISO 639-1 language code (e.g., ’en’, ’es’, ‘fr’)

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

Adds tags to the user profile for categorization and segmentation.

Signature:

Hood('addtags', tags)

Parameters:

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

Example:

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

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

setUsersList()

Sets a list of users for tracking and analytics purposes.

Signature:

Hood('setuserslist', userList)

Parameters:

• userList (array, required): 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

UTM and campaign parameters

setCampaignParams()

Stores UTM and campaign parameters for tracking marketing campaigns.

Signature:

Hood('setcampaignparams', campaignData)

Parameters:

• campaignData (object, required): Object containing campaign parameters

Campaign Parameters:

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

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.

trackSubscription()

Tracks subscription events with type-specific data.

Signature:

Hood('tracksubscription', type, data)

Parameters:

• type (string, required): Subscription type (e.g., ‘S_PUSH’)
• data (object, required): 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()

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

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

pushMessage()

Displays a push notification message via Service Worker.

Signature:

Hood('pushmessage', message, callback?)

Parameters:

• message (object, required): Notification message object
• callback (function, optional): Callback function after showing notification

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

pushStatus()

Gets the current push notification permission status.

Signature:

Hood('pushstatus', callback)

Parameters:

• callback (function, required): 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

Session recording control

startSessionRecording()

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

Stops session recording.

Signature:

Hood('stopsessionrecording')

Example:

Hood('stopsessionrecording');

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

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
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

Event callbacks and listeners

on

Registers event callbacks for internal SDK events.

Signature:

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

Parameters:

• eventName (string, required): Name of the event to listen for
• callback (function, required): Callback function to execute
• options (object, optional): Optional parameters for the event

Available Events:

Example:

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

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

Deprecated Methods

Backward compatibility

// 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:

1. Configuration: config, init
2. User Management: identify, setuserproperties, setuserlanguage
3. Campaign Tracking: setcampaignparams, linkadplatformid
4. Event Tracking: trackevent, tracksubscription, commerce methods
5. Push Notifications: pushrequestpermission, pushmessage, pushstatus
6. Session Management: startsessionrecording, stopsessionrecording
7. Consent: consent
8. 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

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