@mparticle/web-sdk 2.28.2 → 2.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-sdk",
-    "version": "2.28.2",
+    "version": "2.29.0",
     "description": "mParticle core SDK for web applications",
     "license": "Apache-2.0",
     "keywords": [

package/src/aliasRequestApiClient.ts

@@ -0,0 +1,89 @@
+import { IAliasRequest, IAliasCallback } from "./identity.interfaces";
+import { MParticleWebSDK } from "./sdkRuntimeModels";
+import Constants from './constants';
+import { FetchUploader, XHRUploader } from './uploaders';
+import { HTTP_ACCEPTED, HTTP_OK } from "./constants";
+
+
+const { HTTPCodes, Messages } = Constants;
+
+interface IAliasResponseBody {
+    message?: string
+}
+
+export async function sendAliasRequest (mpInstance: MParticleWebSDK, aliasRequest: IAliasRequest, aliasCallback: IAliasCallback) {
+        const { verbose, error } = mpInstance.Logger;
+        const { invokeAliasCallback } = mpInstance._Helpers;
+        const { aliasUrl } = mpInstance._Store.SDKConfig;
+        const { devToken: apiKey } = mpInstance._Store;
+
+        verbose(Messages.InformationMessages.SendAliasHttp);
+
+        // https://go.mparticle.com/work/SQDSDKS-6750
+        const uploadUrl = `https://${aliasUrl}${apiKey}/Alias`;
+        const uploader = window.fetch
+        ? new FetchUploader(uploadUrl)
+        : new XHRUploader(uploadUrl);
+        
+        
+        // https://go.mparticle.com/work/SQDSDKS-6568
+        const uploadPayload = {
+            method: 'post',
+            headers: {
+                Accept: 'text/plain;charset=UTF-8',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(aliasRequest),
+        };
+
+        try {
+            const response = await uploader.upload(uploadPayload);
+
+            let message: string;
+            let aliasResponseBody: IAliasResponseBody;
+
+            // FetchUploader returns the response as a JSON object that we have to await
+            if (response.json) {
+                // HTTP responses of 202, 200, and 403 do not have a response.  response.json will always exist on a fetch, but can only be await-ed when the response is not empty, otherwise it will throw an error.
+                try {
+                    aliasResponseBody = await response.json();
+                } catch (e) {
+                    verbose('The request has no response body');
+                }
+            } else {
+                // https://go.mparticle.com/work/SQDSDKS-6568
+                // XHRUploader returns the response as a string that we need to parse
+                const xhrResponse = response as unknown as XMLHttpRequest;
+                // debugger;
+                aliasResponseBody = xhrResponse.responseText
+                    ? JSON.parse(xhrResponse.responseText)
+                    : '';
+            }
+
+            let errorMessage: string;
+
+            switch (response.status) {
+                case HTTP_OK:
+                case HTTP_ACCEPTED:
+                    // https://go.mparticle.com/work/SQDSDKS-6670
+                    message =
+                        'Successfully sent forwarding stats to mParticle Servers';
+                    break;
+                default:
+                    // 400 has an error message, but 403 doesn't
+                    if (aliasResponseBody?.message) {
+                        errorMessage = aliasResponseBody.message;
+                    }
+                    message =
+                        'Issue with sending Alias Request to mParticle Servers, received HTTP Code of ' +
+                        response.status;
+            }
+
+            verbose(message);
+            invokeAliasCallback(aliasCallback, response.status, errorMessage);
+        } catch (e) {
+            const err = e as Error;
+            error('Error sending alias request to mParticle servers. ' + err);
+            invokeAliasCallback(aliasCallback, HTTPCodes.noHttpCoverage, (err.message));
+        }
+    };

package/src/constants.ts

@@ -174,6 +174,7 @@ const Constants = {
         DirectUrlRouting: 'directURLRouting',
         CacheIdentity: 'cacheIdentity',
         AudienceAPI: 'audienceAPI',
+        CaptureIntegrationSpecificIds: 'captureIntegrationSpecificIds',
     },
     DefaultInstance: 'default_instance',
     CCPAPurpose: 'data_sale_opt_out',
@@ -189,4 +190,10 @@ export default Constants;
 
 // https://go.mparticle.com/work/SQDSDKS-6080
 export const ONE_DAY_IN_SECONDS = 60 * 60 * 24;
-export const MILLIS_IN_ONE_SEC = 1000;
+export const MILLIS_IN_ONE_SEC = 1000;
+
+// https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
+export const HTTP_OK = 200 as const;
+export const HTTP_ACCEPTED = 202 as const;
+export const HTTP_BAD_REQUEST = 400 as const;
+export const HTTP_FORBIDDEN = 403 as const;

package/src/identity.interfaces.ts

@@ -55,7 +55,7 @@ export interface IIdentityAPIRequestData {
     context: string | null;
     environment: Environment;
     request_id: string;
-    reqest_timestamp_unixtime_ms: number;
+    request_timestamp_unixtime_ms: number;
     previous_mpid: MPID | null;
     known_identities: IKnownIdentities;
 }
@@ -115,6 +115,15 @@ export interface IAliasRequest {
     scope?: string;
 }
 
+export interface IAliasCallback {
+    (result: IAliasResult): void;
+}
+
+export interface IAliasResult {
+    httpCode: number;
+    message: string;
+}
+
 export interface SDKIdentityApi {
     HTTPCodes: typeof HTTPCodes;
     identify?(

package/src/identity.js

@@ -1,4 +1,4 @@
-import Constants from './constants';
+import Constants, { HTTP_OK } from './constants';
 import Types from './types';
 import {
     cacheOrClearIdCache,
@@ -13,7 +13,6 @@ const { CacheIdentity } = FeatureFlags;
 const { Identify, Modify, Login, Logout } = IdentityMethods;
 import {
     generateDeprecationMessage,
-    HTTP_SUCCESS,
     isEmpty,
     isFunction,
     isObject,
@@ -1513,7 +1512,7 @@ export default function Identity(mpInstance) {
                 );
             }
 
-            if (identityResponse.status === HTTP_SUCCESS) {
+            if (identityResponse.status === HTTP_OK) {
                 if (getFeatureFlag(CacheIdentity)) {
                     const identityResponseForCache = xhrIdentityResponseAdapter(
                         identityResponse

package/src/identityApiClient.js

@@ -1,5 +1,6 @@
 import Constants from './constants';
 import { xhrIdentityResponseAdapter } from './identity-utils';
+import { sendAliasRequest } from './aliasRequestApiClient';
 
 var HTTPCodes = Constants.HTTPCodes,
     Messages = Constants.Messages;
@@ -7,59 +8,8 @@ var HTTPCodes = Constants.HTTPCodes,
 const { Modify } = Constants.IdentityMethods;
 
 export default function IdentityAPIClient(mpInstance) {
-    this.sendAliasRequest = function(aliasRequest, callback) {
-        var xhr,
-            xhrCallback = function() {
-                if (xhr.readyState === 4) {
-                    // https://go.mparticle.com/work/SQDSDKS-6368
-                    mpInstance.Logger.verbose(
-                        'Received ' + xhr.statusText + ' from server'
-                    );
-                    //only parse error messages from failing requests
-                    if (xhr.status !== 200 && xhr.status !== 202) {
-                        if (xhr.responseText) {
-                            var response = JSON.parse(xhr.responseText);
-                            if (response.hasOwnProperty('message')) {
-                                var errorMessage = response.message;
-                                mpInstance._Helpers.invokeAliasCallback(
-                                    callback,
-                                    xhr.status,
-                                    errorMessage
-                                );
-                                return;
-                            }
-                        }
-                    }
-                    mpInstance._Helpers.invokeAliasCallback(
-                        callback,
-                        xhr.status
-                    );
-                }
-            };
-        mpInstance.Logger.verbose(Messages.InformationMessages.SendAliasHttp);
-
-        xhr = mpInstance._Helpers.createXHR(xhrCallback);
-        if (xhr) {
-            try {
-                xhr.open(
-                    'post',
-                    mpInstance._Helpers.createServiceUrl(
-                        mpInstance._Store.SDKConfig.aliasUrl,
-                        mpInstance._Store.devToken
-                    ) + '/Alias'
-                );
-                xhr.send(JSON.stringify(aliasRequest));
-            } catch (e) {
-                mpInstance._Helpers.invokeAliasCallback(
-                    callback,
-                    HTTPCodes.noHttpCoverage,
-                    e
-                );
-                mpInstance.Logger.error(
-                    'Error sending alias request to mParticle servers. ' + e
-                );
-            }
-        }
+    this.sendAliasRequest = async function(aliasRequest, callback) {
+        await sendAliasRequest(mpInstance, aliasRequest, callback);
     };
 
     this.sendIdentityRequest = function(

package/src/integrationCapture.ts

@@ -0,0 +1,153 @@
+import { SDKEventCustomFlags } from './sdkRuntimeModels';
+import {
+    Dictionary,
+    queryStringParser,
+    getCookies,
+    getHref,
+    isEmpty,
+} from './utils';
+
+export interface IntegrationCaptureProcessorFunction {
+    (clickId: string, url: string, timestamp?: number): string;
+}
+
+// Facebook Click ID has specific formatting rules
+// The formatted ClickID value must be of the form version.subdomainIndex.creationTime.<fbclid>, where:
+// - version is always this prefix: fb
+// - subdomainIndex is which domain the cookie is defined on ('com' = 0, 'example.com' = 1, 'www.example.com' = 2)
+// - creationTime is the UNIX time since epoch in milliseconds when the _fbc was stored. If you don't save the _fbc cookie, use the timestamp when you first observed or received this fbclid value
+// - <fbclid> is the value for the fbclid query parameter in the page URL.
+// https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+export const facebookClickIdProcessor: IntegrationCaptureProcessorFunction = (
+    clickId: string,
+    url: string,
+    timestamp?: number,
+): string => {
+    if (!clickId || !url) {
+        return '';
+    }
+
+    const urlSegments = url?.split('//')
+    if (!urlSegments) {
+        return '';
+    }
+
+    const urlParts = urlSegments[1].split('/');
+    const domainParts = urlParts[0].split('.');
+    let subdomainIndex: number = 1;
+
+    // The rules for subdomainIndex are for parsing the domain portion
+    // of the URL for cookies, but in this case we are parsing the URL 
+    // itself, so we can ignore the use of 0 for 'com'
+    if (domainParts.length >= 3) {
+        subdomainIndex = 2;
+    }
+
+    // If timestamp is not provided, use the current time
+    const _timestamp = timestamp || Date.now();
+
+    return `fb.${subdomainIndex}.${_timestamp}.${clickId}`;
+};
+interface IntegrationIdMapping {
+    [key: string]: {
+        mappedKey: string;
+        processor?: IntegrationCaptureProcessorFunction;
+    };
+}
+
+const integrationMapping: IntegrationIdMapping = {
+    fbclid: {
+        mappedKey: 'Facebook.ClickId',
+        processor: facebookClickIdProcessor,
+    },
+    _fbp: {
+        mappedKey: 'Facebook.BrowserId',
+    },
+    _fbc: {
+        mappedKey: 'Facebook.ClickId',
+    },
+};
+
+export default class IntegrationCapture {
+    public clickIds: Dictionary<string>;
+    public readonly initialTimestamp: number;
+
+    constructor() {
+        this.initialTimestamp = Date.now();
+    }
+
+    /**
+     * Captures Integration Ids from cookies and query params and stores them in clickIds object
+     */
+    public capture(): void {
+        const queryParams = this.captureQueryParams() || {};
+        const cookies = this.captureCookies() || {};
+
+        // Exclude _fbc if fbclid is present
+        // https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc#retrieve-from-fbclid-url-query-parameter
+        if (queryParams['fbclid'] && cookies['_fbc']) {
+            delete cookies['_fbc'];
+        }
+
+        this.clickIds = { ...this.clickIds, ...queryParams, ...cookies };
+    }
+
+    /**
+     * Captures cookies based on the integration ID mapping.
+     */
+    public captureCookies(): Dictionary<string> {
+        const cookies = getCookies(Object.keys(integrationMapping));
+        return this.applyProcessors(cookies);
+    }
+
+    /**
+     * Captures query parameters based on the integration ID mapping.
+     */
+    public captureQueryParams(): Dictionary<string> {
+        const queryParams = this.getQueryParams();
+        return this.applyProcessors(queryParams, getHref(), this.initialTimestamp);
+    }
+
+    /**
+     * Gets the query parameters based on the integration ID mapping.
+     * @returns {Dictionary<string>} The query parameters.
+     */
+    public getQueryParams(): Dictionary<string> {
+        return queryStringParser(getHref(), Object.keys(integrationMapping));
+    }
+
+    /**
+     * Converts captured click IDs to custom flags for SDK events.
+     * @returns {SDKEventCustomFlags} The custom flags.
+     */
+    public getClickIdsAsCustomFlags(): SDKEventCustomFlags {
+        const customFlags: SDKEventCustomFlags = {};
+
+        if (!this.clickIds) {
+            return customFlags;
+        }
+
+        for (const [key, value] of Object.entries(this.clickIds)) {
+            const mappedKey = integrationMapping[key]?.mappedKey;
+            if (!isEmpty(mappedKey)) {
+                customFlags[mappedKey] = value;
+            }
+        }
+        return customFlags;
+    }
+
+    private applyProcessors(clickIds: Dictionary<string>, url?: string, timestamp?: number): Dictionary<string> {
+        const processedClickIds: Dictionary<string> = {};
+
+        for (const [key, value] of Object.entries(clickIds)) {
+            const processor = integrationMapping[key]?.processor;
+            if (processor) {
+                processedClickIds[key] = processor(value, url, timestamp);
+            } else {
+                processedClickIds[key] = value;
+            }
+        }
+
+        return processedClickIds;
+    }
+}

package/src/mp-instance.js

@@ -39,9 +39,10 @@ import IdentityAPIClient from './identityApiClient';
 import { isEmpty, isFunction } from './utils';
 import { LocalStorageVault } from './vault';
 import { removeExpiredIdentityCacheDates } from './identity-utils';
+import IntegrationCapture from './integrationCapture';
 
 const { Messages, HTTPCodes, FeatureFlags } = Constants;
-const { ReportBatching } = FeatureFlags;
+const { ReportBatching, CaptureIntegrationSpecificIds } = FeatureFlags;
 const { StartingInitialization } = Messages.InformationMessages;
 
 /**
@@ -77,6 +78,7 @@ export default function mParticleInstance(instanceName) {
         integrationDelays: {},
         forwarderConstructors: [],
     };
+    this._IntegrationCapture = new IntegrationCapture();
 
     // required for forwarders once they reference the mparticle instance
     this.IdentityType = Types.IdentityType;
@@ -1336,6 +1338,10 @@ function completeSDKInitialization(apiKey, config, mpInstance) {
             mpInstance._ForwardingStatsUploader.startForwardingStatsTimer();
         }
 
+        if (mpInstance._Helpers.getFeatureFlag(CaptureIntegrationSpecificIds)) {
+            mpInstance._IntegrationCapture.capture();
+        }
+
         mpInstance._Forwarders.processForwarders(
             config,
             mpInstance._APIClient.prepareForwardingStats

package/src/sdkRuntimeModels.ts

@@ -16,7 +16,11 @@ import { IPersistence } from './persistence.interfaces';
 import { IMPSideloadedKit } from './sideloadedKit';
 import { ISessionManager } from './sessionManager';
 import { Kit, MPForwarder } from './forwarders.interfaces';
-import { IIdentity, SDKIdentityApi } from './identity.interfaces';
+import {
+    IIdentity,
+    SDKIdentityApi,
+    IAliasCallback,
+} from './identity.interfaces';
 import {
     ISDKUserAttributeChangeData,
     ISDKUserIdentityChanges,
@@ -26,6 +30,7 @@ import {
     ISDKUserAttributes,
 } from './identity-user-interfaces';
 import { IIdentityType } from './types.interfaces';
+import IntegrationCapture from './integrationCapture';
 
 // TODO: Resolve this with version in @mparticle/web-sdk
 export type SDKEventCustomFlags = Dictionary<any>;
@@ -146,6 +151,7 @@ interface IEvents {
 
 export interface MParticleWebSDK {
     addForwarder(mockForwarder: MPForwarder): void;
+    _IntegrationCapture: IntegrationCapture;
     IdentityType: IIdentityType;
     _Identity: IIdentity;
     Identity: SDKIdentityApi;
@@ -265,6 +271,11 @@ export interface SDKHelpersApi {
     generateHash?(value: string): string;
     // https://go.mparticle.com/work/SQDSDKS-6317
     getFeatureFlag?(feature: string): boolean | string; // TODO: Feature Constants should be converted to enum
+    invokeAliasCallback(
+        aliasCallback: IAliasCallback,
+        number: number,
+        errorMessage: string
+    ): void;
     isDelayedByIntegration?(
         delayedIntegrations: Dictionary<boolean>,
         timeoutStart: number,

package/src/serverModel.ts

@@ -8,6 +8,7 @@ import {
     BaseEvent,
     MParticleWebSDK,
     SDKEvent,
+    SDKEventCustomFlags,
     SDKGeoLocation,
     SDKProduct,
 } from './sdkRuntimeModels';
@@ -317,6 +318,18 @@ export default function ServerModel(
             event.messageType === Types.MessageType.OptOut ||
             mpInstance._Store.webviewBridgeEnabled
         ) {
+            let customFlags: SDKEventCustomFlags = {...event.customFlags};
+
+            // https://go.mparticle.com/work/SQDSDKS-5053
+            if (mpInstance._Helpers.getFeatureFlag && mpInstance._Helpers.getFeatureFlag(Constants.FeatureFlags.CaptureIntegrationSpecificIds)) {
+
+                // Attempt to recapture click IDs in case a third party integration
+                // has added or updated  new click IDs since the last event was sent.
+                mpInstance._IntegrationCapture.capture();
+                const transformedClickIDs = mpInstance._IntegrationCapture.getClickIdsAsCustomFlags();
+                customFlags = {...transformedClickIDs, ...customFlags};
+            }
+
             if (event.hasOwnProperty('toEventAPIObject')) {
                 eventObject = event.toEventAPIObject();
             } else {
@@ -336,7 +349,7 @@ export default function ServerModel(
                         event.sourceMessageId ||
                         mpInstance._Helpers.generateUniqueId(),
                     EventDataType: event.messageType,
-                    CustomFlags: event.customFlags || {},
+                    CustomFlags: customFlags,
                     UserAttributeChanges: event.userAttributeChanges,
                     UserIdentityChanges: event.userIdentityChanges,
                 };

package/src/store.ts

@@ -710,6 +710,7 @@ export function processFlags(config: SDKInitConfig): IFeatureFlags {
         DirectUrlRouting,
         CacheIdentity,
         AudienceAPI,
+        CaptureIntegrationSpecificIds,
     } = Constants.FeatureFlags;
 
     if (!config.flags) {
@@ -727,6 +728,7 @@ export function processFlags(config: SDKInitConfig): IFeatureFlags {
     flags[DirectUrlRouting] = config.flags[DirectUrlRouting] === 'True';
     flags[CacheIdentity] = config.flags[CacheIdentity] === 'True';
     flags[AudienceAPI] = config.flags[AudienceAPI] === 'True';
+    flags[CaptureIntegrationSpecificIds] = config.flags[CaptureIntegrationSpecificIds] === 'True';
 
     return flags;
 }

package/src/uploaders.ts

@@ -47,6 +47,7 @@ export class XHRUploader extends AsyncUploader {
     // 3   LOADING Downloading; responseText holds partial data.
     // 4   DONE    The operation is complete.
 
+    // https://go.mparticle.com/work/SQDSDKS-6736
     private async makeRequest(
         url: string,
         data: string,
@@ -58,13 +59,17 @@ export class XHRUploader extends AsyncUploader {
                 if (xhr.readyState !== 4) return;
 
                 // Process the response
-                if (xhr.status >= 200 && xhr.status < 300) {
-                    resolve(xhr as unknown as Response);
-                } else {
-                    reject(xhr);
-                }
+                // We resolve all xhr responses whose ready state is 4 regardless of HTTP codes that may be errors (400+)
+                // because these are valid HTTP responses.
+                resolve((xhr as unknown) as Response);
             };
 
+            // Reject a promise only when there is an xhr error
+            xhr.onerror = () => {
+                reject((xhr as unknown) as Response);
+            };
+
+
             xhr.open(method, url);
             xhr.send(data);
         });

package/src/utils.ts

@@ -9,8 +9,6 @@ export type Dictionary<V = any> = Record<string, V>;
 
 export type Environment = 'development' | 'production';
 
-export const HTTP_SUCCESS = 200 as const;
-
 const createCookieString = (value: string): string =>
     replaceCommasWithPipes(replaceQuotesWithApostrophes(value));
 
@@ -224,7 +222,7 @@ const isDataPlanSlug = (str: string): boolean => str === toDataPlanSlug(str);
 const isStringOrNumber = (value: any): boolean =>
     isString(value) || isNumber(value);
 
-const isEmpty = (value: Dictionary<any> | null | undefined): boolean =>
+const isEmpty = (value: Dictionary<any> | string | null | undefined): boolean =>
     value == null || !(Object.keys(value) || value).length;
 
 const mergeObjects = <T extends object>(...objects: T[]): T => {
@@ -234,6 +232,107 @@ const mergeObjects = <T extends object>(...objects: T[]): T => {
 const moveElementToEnd = <T>(array: T[], index: number): T[] =>
     array.slice(0, index).concat(array.slice(index + 1), array[index]);
 
+const queryStringParser = (
+    url: string,
+    keys: string[] = []
+): Dictionary<string> => {
+    let urlParams: URLSearchParams | URLSearchParamsFallback;
+    let results: Dictionary<string> = {};
+
+    if (!url) return results;
+
+    if (typeof URL !== 'undefined' && typeof URLSearchParams !== 'undefined') {
+        const urlObject = new URL(url);
+        urlParams = new URLSearchParams(urlObject.search);
+    } else {
+        urlParams = queryStringParserFallback(url);
+    }
+
+    if (isEmpty(keys)) {
+        urlParams.forEach((value, key) => {
+            results[key] = value;
+        });
+    } else {
+        keys.forEach(key => {
+            const value = urlParams.get(key);
+            if (value) {
+                results[key] = value;
+            }
+        });
+    }
+
+    return results;
+};
+
+interface URLSearchParamsFallback {
+    get: (key: string) => string | null;
+    forEach: (callback: (value: string, key: string) => void) => void;
+}
+
+const queryStringParserFallback = (url: string): URLSearchParamsFallback => {
+    let params: Dictionary<string> = {};
+    const queryString = url.split('?')[1] || '';
+    const pairs = queryString.split('&');
+
+    pairs.forEach(pair => {
+        var [key, value] = pair.split('=');
+        if (key && value) {
+            params[key] = decodeURIComponent(value || '');
+        }
+    });
+
+    return {
+        get: function(key: string) {
+            return params[key];
+        },
+        forEach: function(callback: (value: string, key: string) => void) {
+            for (var key in params) {
+                if (params.hasOwnProperty(key)) {
+                    callback(params[key], key);
+                }
+            }
+        },
+    };
+};
+
+// Get cookies as a dictionary
+const getCookies = (keys?: string[]): Dictionary<string> => {
+    // Helper function to parse cookies from document.cookie
+    const parseCookies = (): string[] => {
+        if (typeof window === 'undefined') {
+            return [];
+        }
+        return window.document.cookie.split(';').map(cookie => cookie.trim());
+    };
+
+    // Helper function to filter cookies by keys
+    const filterCookies = (
+        cookies: string[],
+        keys?: string[]
+    ): Dictionary<string> => {
+        const results: Dictionary<string> = {};
+        for (const cookie of cookies) {
+            const [key, value] = cookie.split('=');
+            if (!keys || keys.includes(key)) {
+                results[key] = value;
+            }
+        }
+        return results;
+    };
+
+    // Parse cookies from document.cookie
+    const parsedCookies: string[] = parseCookies();
+
+    // Filter cookies by keys if provided
+    return filterCookies(parsedCookies, keys);
+};
+
+const getHref = (): string => {
+    return typeof window !== 'undefined' && window.location
+        ? window.location.href
+        : '';
+};
+
 export {
     createCookieString,
     revertCookieString,
@@ -264,4 +363,7 @@ export {
     isValidCustomFlagProperty,
     mergeObjects,
     moveElementToEnd,
+    queryStringParser,
+    getCookies,
+    getHref,
 };