api.ts

/*
 * Copyright (c) 2022 Snowplow Analytics Ltd, 2010 Anthon Pang
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived from
 *    this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

import {
  dispatchToTrackers,
  ActivityTrackingConfiguration,
  ActivityTrackingConfigurationCallback,
  ActivityCallback,
  ActivityCallbackData,
  BrowserPlugin,
  BrowserPluginConfiguration,
  BuiltInContexts,
  DisableAnonymousTrackingConfiguration,
  EnableAnonymousTrackingConfiguration,
  AnonymousTrackingOptions,
  FlushBufferConfiguration,
  PageViewEvent,
  ClearUserDataConfiguration,
} from '@snowplow/browser-tracker-core';
import {
  buildSelfDescribingEvent,
  buildStructEvent,
  CommonEventProperties,
  ConditionalContextProvider,
  ContextPrimitive,
  ContextGenerator,
  FilterProvider,
  RuleSetProvider,
  SelfDescribingEvent,
  SelfDescribingJson,
  StructuredEvent,
  ContextEvent,
  ContextFilter,
  RuleSet,
} from '@snowplow/tracker-core';

export {
  ActivityTrackingConfiguration,
  ActivityTrackingConfigurationCallback,
  ActivityCallback,
  ActivityCallbackData,
  BrowserPlugin,
  BrowserPluginConfiguration,
  BuiltInContexts,
  FlushBufferConfiguration,
  PageViewEvent,
  EnableAnonymousTrackingConfiguration,
  DisableAnonymousTrackingConfiguration,
  AnonymousTrackingOptions,
  ClearUserDataConfiguration,
  ConditionalContextProvider,
  ContextPrimitive,
  SelfDescribingEvent,
  SelfDescribingJson,
  CommonEventProperties,
  StructuredEvent,
  ContextGenerator,
  FilterProvider,
  RuleSetProvider,
  ContextEvent,
  ContextFilter,
  RuleSet,
};

/**
 * Expires current session and starts a new session.
 *
 * @param trackers - The tracker identifiers which will have their session refreshed
 */
export function newSession(trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.newSession();
  });
}

/**
 * Override referrer
 *
 * @param url - Custom Referrer which will be used as override
 * @param trackers - The tracker identifiers which will be configured
 */
export function setReferrerUrl(url: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setReferrerUrl(url);
  });
}

/**
 * Override url
 *
 * @param url - Custom URL which will be used as override
 * @param trackers - The tracker identifiers which will be configured
 */
export function setCustomUrl(url: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setCustomUrl(url);
  });
}

/**
 * Override document.title
 *
 * @param title - Document title which will be used as override
 * @param trackers - The tracker identifiers which will be configured
 */
export function setDocumentTitle(title: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setDocumentTitle(title);
  });
}

/**
 * Strip hash tag (or anchor) from URL
 *
 * @param enable - Whether to enable stripping of hash
 * @param trackers - The tracker identifiers which will be configured
 */
export function discardHashTag(enable: boolean, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.discardHashTag(enable);
  });
}

/**
 * Strip braces from URL
 *
 * @param enable - Whther to enable stripping of braces
 * @param trackers - The tracker identifiers which will be configured
 */
export function discardBrace(enable: boolean, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.discardBrace(enable);
  });
}

/**
 * Set first-party cookie path
 *
 * @param path - The path which will be used when setting cookies
 * @param trackers - The tracker identifiers which will be configured
 */
export function setCookiePath(path: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setCookiePath(path);
  });
}

/**
 * Set visitor cookie timeout (in seconds)
 *
 * @param timeout - The timeout until cookies will expire
 * @param trackers - The tracker identifiers which will be configured
 */
export function setVisitorCookieTimeout(timeout: number, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setVisitorCookieTimeout(timeout);
  });
}

/**
 * Enable querystring decoration for links pasing a filter
 *
 * @param crossDomainLinker - Function used to determine which links to decorate
 * @param trackers - The tracker identifiers which will be configured
 */
export function crossDomainLinker(
  crossDomainLinkerCriterion: (elt: HTMLAnchorElement | HTMLAreaElement) => boolean,
  trackers?: Array<string>
) {
  dispatchToTrackers(trackers, (t) => {
    t.crossDomainLinker(crossDomainLinkerCriterion);
  });
}

/**
 * Enables page activity tracking (sends page pings to the Collector regularly).
 *
 * @param configuration - The activity tracking configuration
 * @param trackers - The tracker identifiers which will be configured
 */
export function enableActivityTracking(configuration: ActivityTrackingConfiguration, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.enableActivityTracking(configuration);
  });
}

/**
 * Enables page activity tracking (replaces collector ping with callback).
 *
 * @param configuration - The activity tracking callback configuration
 * @param trackers - The tracker identifiers which will be configured
 */
export function enableActivityTrackingCallback(
  configuration: ActivityTrackingConfiguration & ActivityTrackingConfigurationCallback,
  trackers?: Array<string>
) {
  dispatchToTrackers(trackers, (t) => {
    t.enableActivityTrackingCallback(configuration);
  });
}

/**
 * Disables page activity tracking.
 *
 * @param trackers - The tracker identifiers the activity tracking will be disabled.
 */
export function disableActivityTracking(trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.disableActivityTracking();
  });
}

/**
 * Disables page activity tracking callback.
 *
 * @param trackers - The tracker identifiers the activity tracking callback will be disabled.
 */
export function disableActivityTrackingCallback(trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.disableActivityTrackingCallback();
  });
}

/**
 * Triggers the activityHandler manually to allow external user defined activity. i.e. While watching a video
 *
 * @param trackers - The tracker identifiers which will be updated
 */
export function updatePageActivity(trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.updatePageActivity();
  });
}

/**
 * Sets the opt out cookie.
 *
 * @param name - of the opt out cookie
 * @param trackers - The tracker identifiers which will be configured
 */
export function setOptOutCookie(name?: string | null, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setOptOutCookie(name);
  });
}

/**
 * Set the business-defined user ID for this user.
 *
 * @param userId - The business-defined user ID
 * @param trackers - The tracker identifiers which will be configured
 */
export function setUserId(userId?: string | null, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setUserId(userId);
  });
}

/**
 * Set the business-defined user ID for this user using the location querystring.
 *
 * @param querystringField - Name of a querystring name-value pair
 * @param trackers - The tracker identifiers which will be configured
 */
export function setUserIdFromLocation(querystringField: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setUserIdFromLocation(querystringField);
  });
}

/**
 * Set the business-defined user ID for this user using the referrer querystring.
 *
 * @param querystringField - Name of a querystring name-value pair
 * @param trackers - The tracker identifiers which will be configured
 */
export function setUserIdFromReferrer(querystringField: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setUserIdFromReferrer(querystringField);
  });
}

/**
 * Set the business-defined user ID for this user to the value of a cookie.
 *
 * @param cookieName - Name of the cookie whose value will be assigned to businessUserId
 * @param trackers - The tracker identifiers which will be configured
 */
export function setUserIdFromCookie(cookieName: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setUserIdFromCookie(cookieName);
  });
}

/**
 * Specify the Snowplow collector URL. Specific http or https to force it
 * or leave it off to match the website protocol.
 *
 * @param collectorUrl - The collector URL, with or without protocol
 * @param trackers - The tracker identifiers which will be configured
 */
export function setCollectorUrl(collectorUrl: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setCollectorUrl(collectorUrl);
  });
}

/**
 * Set the buffer size
 * Can be useful if you want to stop batching requests to ensure events start
 * sending closer to event creation
 *
 * @param newBufferSize - The value with which to update the bufferSize to
 * @param trackers - The tracker identifiers which will be flushed
 */
export function setBufferSize(newBufferSize: number, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setBufferSize(newBufferSize);
  });
}

/**
 * Send all events in the outQueue
 * Only need to use this when sending events with a bufferSize of at least 2
 *
 * @param configuration - The configuration to use following flushing the buffer
 * @param trackers - The tracker identifiers which will be flushed
 */
export function flushBuffer(configuration?: FlushBufferConfiguration, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.flushBuffer(configuration);
  });
}

/**
 * Track a visit to a web page
 *
 * @param event - The Page View Event properties
 * @param trackers - The tracker identifiers which the event will be sent to
 */
export function trackPageView(event?: PageViewEvent & CommonEventProperties, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.trackPageView(event);
  });
}

/**
 * Track a structured event
 * A classic style of event tracking, allows for easier movement between analytics
 * systems. A loosely typed event, creating a Self Describing event is preferred, but
 * useful for interoperability.
 *
 * @param event - The Structured Event properties
 * @param trackers - The tracker identifiers which the event will be sent to
 */
export function trackStructEvent(event: StructuredEvent & CommonEventProperties, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.core.track(buildStructEvent(event), event.context, event.timestamp);
  });
}

/**
 * Track a self-describing event happening on this page.
 * A custom event type, allowing for an event to be tracked using your own custom schema
 * and a data object which conforms to the supplied schema
 *
 * @param event - The event information
 * @param trackers - The tracker identifiers which the event will be sent to
 */
export function trackSelfDescribingEvent(event: SelfDescribingEvent & CommonEventProperties, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.core.track(buildSelfDescribingEvent({ event: event.event }), event.context, event.timestamp);
  });
}

/**
 * All provided contexts will be sent with every event
 *
 * @param contexts - An array of contexts or conditional contexts
 * @param trackers - The tracker identifiers which the global contexts will be added to
 */
export function addGlobalContexts(
  contexts: Array<ConditionalContextProvider | ContextPrimitive>,
  trackers?: Array<string>
) {
  dispatchToTrackers(trackers, (t) => {
    t.core.addGlobalContexts(contexts);
  });
}

/**
 * All provided contexts will no longer be sent with every event
 *
 * @param contexts - An array of contexts or conditional contexts
 * @param trackers - The tracker identifiers which the global contexts will be remove from
 */
export function removeGlobalContexts(
  contexts: Array<ConditionalContextProvider | ContextPrimitive>,
  trackers?: Array<string>
) {
  dispatchToTrackers(trackers, (t) => {
    t.core.removeGlobalContexts(contexts);
  });
}

/**
 * Clear all global contexts that are sent with events
 *
 * @param trackers - The tracker identifiers which the global contexts will be cleared from
 */
export function clearGlobalContexts(trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.core.clearGlobalContexts();
  });
}

/**
 * Stop regenerating `pageViewId` (available from `web_page` context)
 *
 * @param trackers - The tracker identifiers which the event will preserve their Page View Ids
 */
export function preservePageViewId(trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.preservePageViewId();
  });
}

/**
 * Disables anonymous tracking if active (ie. tracker initialized with `anonymousTracking`)
 * For stateStorageStrategy override, uses supplied value first,
 * falls back to one defined in initial config, otherwise uses cookieAndLocalStorage.
 *
 * @param configuration - The configuration for disabling anonymous tracking
 * @param trackers - The tracker identifiers which the event will be sent to
 */
export function disableAnonymousTracking(
  configuration?: DisableAnonymousTrackingConfiguration,
  trackers?: Array<string>
) {
  dispatchToTrackers(trackers, (t) => {
    t.disableAnonymousTracking(configuration);
  });
}

/**
 * Enables anonymous tracking (ie. tracker initialized without `anonymousTracking`)
 *
 * @param configuration - The configuration for enabling anonymous tracking
 * @param trackers - The tracker identifiers which the event will be sent to
 */
export function enableAnonymousTracking(
  configuration?: EnableAnonymousTrackingConfiguration,
  trackers?: Array<string>
) {
  dispatchToTrackers(trackers, (t) => {
    t.enableAnonymousTracking(configuration);
  });
}

/**
 * Clears all cookies and local storage containing user and session identifiers
 *
 * @param trackers - The tracker identifiers which the event will be sent to
 */
export function clearUserData(configuration?: ClearUserDataConfiguration, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.clearUserData(configuration);
  });
}

/**
 * Add a plugin into the plugin collection after trackers have already been initialised
 *
 * @param configuration - The plugin to add
 * @param trackers - The tracker identifiers which the plugin will be added to
 */
export function addPlugin(configuration: BrowserPluginConfiguration, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.addPlugin(configuration);
  });
}

/**
 * Set the business-defined network user ID for this user.
 *
 * @param networkUserId - The business-defined network user ID
 * @param trackers - The tracker identifiers which will be configured
 */
export function setNetworkUserId(networkUserId: string, trackers?: Array<string>) {
  dispatchToTrackers(trackers, (t) => {
    t.setNetworkUserId(networkUserId);
  });
}