saasco-sdk 0.1.41 → 0.1.42

package/index.cjs.js

@@ -8,7 +8,7 @@ var jsSha256 = require('js-sha256');
 var uuid$1 = require('@lukeed/uuid');
 var zod = require('zod');
 
-var version = "0.1.41";
+var version = "0.1.42";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -555,8 +555,8 @@ function getBrowserContext() {
   };
 }
 
-const isBrowser$1 = typeof window !== 'undefined';
-const isServer$1 = !isBrowser$1;
+const isBrowser$2 = typeof window !== 'undefined';
+const isServer$2 = !isBrowser$2;
 const standardFacebookEvents = ['AddPaymentInfo', 'AddToCart', 'AddToWishlist', 'CompleteRegistration', 'Contact', 'CustomizeProduct', 'Donate', 'FindLocation', 'InitiateCheckout', 'Lead', 'Purchase', 'Schedule', 'Search', 'StartTrial', 'SubmitApplication', 'Subscribe', 'ViewContent', 'PageView'];
 /**
  * Create a Facebook Pixel integration instance
@@ -567,7 +567,7 @@ function createFacebookPixelIntegration(config) {
     name: 'facebook-pixel',
     environments: ['client'],
     init: () => tslib.__awaiter(this, void 0, void 0, function* () {
-      if (isServer$1) {
+      if (isServer$2) {
         // On server, Facebook Pixel is a no-op but doesn't throw
         // This allows the integration to be registered but remain inactive
         return;
@@ -646,6 +646,10 @@ function createFacebookPixelIntegration(config) {
           const amValues = coerceMetaConversionsAmValues(Object.assign(Object.assign({}, properties || {}), userId ? {
             external_id: userId
           } : {}));
+          // Advanced Matching
+          // Add event to identify user and hash email field
+          // FB pixel handles hashing automatically
+          // https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
           const am = {};
           if (amValues.external_id) am['external_id'] = amValues.external_id;
           if (amValues.em) am['em'] = jsSha256.sha256(amValues.em);
@@ -674,6 +678,18 @@ function getFacebookEventName(eventName, eventMapping) {
   if (!eventMapping) return eventName;
   return eventMapping[eventName] || eventName;
 }
+/**
+ * Get Advanced Matching values from properties
+ *
+ * Documentation for Pixel
+ * https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
+ *
+ * Documentation for Conversions API
+ * https://developers.secure.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+ *
+ * @param properties
+ * @returns
+ */
 function coerceMetaConversionsAmValues(properties) {
   const coerce = [{
     key: 'em',
@@ -781,6 +797,214 @@ function coerceMetaConversionsAmValues(properties) {
     }
   }];
   const result = {};
+  for (const {
+    key,
+    coerceFrom,
+    transform
+  } of coerce) {
+    const foundValue = findFirstProperty$1(properties, coerceFrom);
+    if (foundValue !== null && transform) {
+      const transformedValue = transform(foundValue);
+      if (transformedValue) {
+        result[key] = transformedValue;
+      }
+    } else if (foundValue !== null && typeof foundValue === 'string') {
+      result[key] = foundValue;
+    }
+  }
+  return result;
+}
+function findFirstProperty$1(properties, keys) {
+  for (const key of keys) {
+    if (properties[key] !== undefined) {
+      return properties[key];
+    }
+  }
+  return null;
+}
+
+/**
+ * TikTok Pixel Integration
+ *
+ * This integration provides TikTok Pixel tracking capabilities including:
+ * - Event tracking for standard and custom events
+ * - Advanced matching with hashed user identification data
+ * - Automatic script loading and initialization
+ *
+ * Key Resources:
+ * - Advanced Matching: https://business-api.tiktok.com/portal/docs?rid=5ipocbxyw8v&id=1739585700402178
+ * - Standard Events: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+const isBrowser$1 = typeof window !== 'undefined';
+const isServer$1 = !isBrowser$1;
+/**
+ * Standard TikTok events supported by the pixel
+ *
+ * Note: This list reflects TikTok's official standard events. Events like 'CompletePayment'
+ * are not standard events and should be tracked as custom events if needed.
+ *
+ * Documentation: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+const standardTikTokEvents = ['AddPaymentInfo', 'AddToCart', 'AddToWishlist', 'ApplicationApproval', 'CompleteRegistration', 'Contact', 'CustomizeProduct', 'Download', 'FindLocation', 'InitiateCheckout', 'Lead', 'Purchase', 'Schedule', 'Search', 'StartTrial', 'SubmitApplication', 'Subscribe', 'ViewContent', 'PageView'];
+/**
+ * Create a TikTok Pixel integration instance
+ */
+function createTikTokPixelIntegration(config) {
+  let isPixelReady = false;
+  return {
+    name: 'tiktok-pixel',
+    environments: ['client'],
+    init: () => tslib.__awaiter(this, void 0, void 0, function* () {
+      if (isServer$1) {
+        // On server, TikTok Pixel is a no-op but doesn't throw
+        // This allows the integration to be registered but remain inactive
+        return;
+      }
+      // Check if TikTok Pixel is already loaded
+      if (window.ttq) {
+        console.warn('TikTok Pixel is already initialized');
+        isPixelReady = true;
+        return;
+      }
+      // Initialize TikTok Pixel
+      return new Promise((resolve, reject) => {
+        try {
+          (function (w, d, t) {
+            w.TiktokAnalyticsObject = t;
+            const ttq = w[t] = w[t] || [];
+            ttq.methods = ['page', 'track', 'identify', 'instances', 'debug', 'on', 'off', 'once', 'ready', 'alias', 'group', 'enableCookie', 'disableCookie', 'holdConsent', 'revokeConsent', 'grantConsent'];
+            ttq.setAndDefer = function (t, e) {
+              t[e] = function () {
+                t.push([e].concat(Array.prototype.slice.call(arguments, 0)));
+              };
+            };
+            for (let i = 0; i < ttq.methods.length; i++) ttq.setAndDefer(ttq, ttq.methods[i]);
+            ttq.instance = function (t) {
+              const e = ttq._i[t] || [];
+              for (let n = 0; n < ttq.methods.length; n++) ttq.setAndDefer(e, ttq.methods[n]);
+              return e;
+            };
+            ttq.load = function (e, n) {
+              const r = 'https://analytics.tiktok.com/i18n/pixel/events.js';
+              const o = n && n.partner;
+              ttq._i = ttq._i || {};
+              ttq._i[e] = [];
+              ttq._i[e]._u = r;
+              ttq._t = ttq._t || {};
+              ttq._t[e] = +new Date();
+              ttq._o = ttq._o || {};
+              ttq._o[e] = n || {};
+              const script = document.createElement('script');
+              script.type = 'text/javascript';
+              script.async = true;
+              script.src = r + '?sdkid=' + e + '&lib=' + t;
+              // Add load event listener
+              script.onload = () => {
+                isPixelReady = true;
+                resolve();
+              };
+              script.onerror = () => {
+                reject(new Error('Failed to load TikTok Pixel script'));
+              };
+              const firstScript = document.getElementsByTagName('script')[0];
+              firstScript.parentNode.insertBefore(script, firstScript);
+            };
+            // Load the pixel with the provided ID
+            ttq.load(config.pixelId, config.testMode ? {
+              test_mode: true
+            } : undefined);
+            ttq.page();
+            // If script loads synchronously, mark as ready
+            if (window.ttq && typeof window.ttq === 'function') {
+              isPixelReady = true;
+              resolve();
+            }
+          })(window, document, 'ttq');
+        } catch (error) {
+          reject(error);
+        }
+      });
+    }),
+    track: (eventName, properties, context) => {
+      if (!isPixelReady || !window.ttq) return;
+      const ttEventName = getTikTokEventName(eventName, config.eventMapping);
+      // Handle PageView separately as it uses ttq.page()
+      if (ttEventName === 'PageView') {
+        window.ttq.page();
+        return;
+      }
+      // Map parameters based on specific event requirements
+      const ttParams = mapTikTokEventParameters(ttEventName, properties);
+      if (ttParams && Object.keys(ttParams).length > 0) {
+        window.ttq.track(ttEventName, ttParams);
+      } else {
+        window.ttq.track(ttEventName);
+      }
+    },
+    identify: (userId, properties, context) => {
+      try {
+        if (typeof window !== 'undefined' && window.ttq) {
+          const identifyData = coerceTikTokIdentifyValues(Object.assign(Object.assign({}, properties || {}), userId ? {
+            external_id: userId
+          } : {}));
+          if (Object.keys(identifyData).length > 0) {
+            window.ttq.identify(identifyData);
+          }
+        }
+      } catch (error) {
+        console.error('Error identifying user in TikTok Pixel:', error);
+      }
+    }
+  };
+}
+function getTikTokEventName(eventName, eventMapping) {
+  // Convert default saasco Page View event by default
+  if (eventName === 'Page View') return 'PageView';
+  if (!eventMapping) return eventName;
+  return eventMapping[eventName] || eventName;
+}
+/**
+ * Get identification values from properties for TikTok Pixel
+ *
+ * Advanced Matching Documentation:
+ * https://business-api.tiktok.com/portal/docs?rid=5ipocbxyw8v&id=1739585700402178
+ *
+ * Standard Events Documentation:
+ * https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ *
+ * @param properties
+ * @returns
+ */
+function coerceTikTokIdentifyValues(properties) {
+  const coerce = [{
+    key: 'email',
+    coerceFrom: ['email', 'user_email', 'userEmail', 'email_address', 'emailAddress', 'e_mail', 'E_Mail', 'mail', 'Mail', 'contact_email', 'contactEmail', 'primary_email', 'primaryEmail'],
+    transform: value => {
+      if (typeof value !== 'string') return undefined;
+      const normalized = value.trim().toLowerCase();
+      // TikTok requires hashed email
+      return normalized ? jsSha256.sha256(normalized) : undefined;
+    }
+  }, {
+    key: 'phone_number',
+    coerceFrom: ['phone', 'phone_number', 'phoneNumber', 'mobile', 'mobile_number', 'mobileNumber', 'contact_number', 'contactNumber', 'tel', 'telephone'],
+    transform: value => {
+      if (typeof value !== 'string' && typeof value !== 'number') return undefined;
+      const phoneStr = String(value).replace(/\D/g, '');
+      // TikTok requires hashed phone number
+      return phoneStr ? jsSha256.sha256(phoneStr) : undefined;
+    }
+  }, {
+    key: 'external_id',
+    coerceFrom: ['external_id', 'externalId', 'user_id', 'userId', 'id', 'distinctId', 'distinct_id', 'customer_id', 'customerId', 'member_id', 'memberId'],
+    transform: value => {
+      if (value == null) return undefined;
+      const stringValue = String(value);
+      // TikTok requires hashed external_id
+      return stringValue ? jsSha256.sha256(stringValue) : undefined;
+    }
+  }];
+  const result = {};
   for (const {
     key,
     coerceFrom,
@@ -806,6 +1030,63 @@ function findFirstProperty(properties, keys) {
   }
   return null;
 }
+/**
+ * Maps event properties to TikTok-specific parameters based on event type
+ *
+ * Parameter Documentation: https://ads.tiktok.com/help/article/about-parameters
+ * Standard Events: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+function mapTikTokEventParameters(eventName, properties) {
+  if (!properties) return null;
+  const params = {};
+  // Helper to safely add parameters, skipping objects/null/undefined
+  const addParam = (key, value) => {
+    if (value != null && typeof value !== 'object') {
+      params[key] = value;
+    }
+  };
+  switch (eventName) {
+    case 'AddToCart':
+    case 'Purchase':
+    case 'ViewContent':
+      addParam('content_type', properties['content_type']);
+      addParam('content_ids', properties['content_ids']);
+      addParam('quantity', properties['quantity']);
+      addParam('description', properties['description']);
+      addParam('currency', properties['currency']);
+      addParam('value', properties['value']);
+      addParam('content_name', properties['content_name']);
+      addParam('content_category', properties['content_category']);
+      break;
+    case 'StartTrial':
+      addParam('content_ids', properties['content_ids']);
+      addParam('currency', properties['currency']);
+      addParam('value', properties['value']);
+      break;
+    case 'Search':
+      const searchString = properties['search_string'] || properties['query'] || properties['search_query'];
+      addParam('search_string', searchString);
+      break;
+    case 'InitiateCheckout':
+    case 'AddPaymentInfo':
+      addParam('value', properties['value']);
+      addParam('currency', properties['currency']);
+      addParam('content_ids', properties['content_ids']);
+      addParam('quantity', properties['quantity']);
+      break;
+    case 'CompleteRegistration':
+    case 'Subscribe':
+      addParam('value', properties['value']);
+      addParam('currency', properties['currency']);
+      break;
+    default:
+      // Pass through common parameters for any other events
+      addParam('value', properties['value']);
+      addParam('currency', properties['currency']);
+      break;
+  }
+  return Object.keys(params).length > 0 ? params : null;
+}
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 class AnalyticsLogger {
@@ -1334,6 +1615,10 @@ class Saasco {
             this.logger.log('Registering Facebook Pixel integration with ID:', integrationConfig.config.pixelId);
             const fbIntegration = createFacebookPixelIntegration(integrationConfig.config);
             yield this.integrationManager.registerIntegration(fbIntegration);
+          } else if (integrationConfig.type === 'tiktok-pixel') {
+            this.logger.log('Registering TikTok Pixel integration with ID:', integrationConfig.config.pixelId);
+            const tiktokIntegration = createTikTokPixelIntegration(integrationConfig.config);
+            yield this.integrationManager.registerIntegration(tiktokIntegration);
           }
         } catch (error) {
           this.logger.log(`Failed to register ${integrationConfig.type} integration:`, error);
@@ -1599,6 +1884,8 @@ exports.Logger = Logger;
 exports.Saasco = Saasco;
 exports.browserContextSchema = browserContextSchema;
 exports.createFacebookPixelIntegration = createFacebookPixelIntegration;
+exports.createTikTokPixelIntegration = createTikTokPixelIntegration;
 exports.getBrowserContext = getBrowserContext;
 exports.standardFacebookEvents = standardFacebookEvents;
+exports.standardTikTokEvents = standardTikTokEvents;
 exports.timezones = timezones;

package/index.esm.js

@@ -4,7 +4,7 @@ import { sha256 } from 'js-sha256';
 import { v4 } from '@lukeed/uuid';
 import { z } from 'zod';
 
-var version = "0.1.41";
+var version = "0.1.42";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -551,8 +551,8 @@ function getBrowserContext() {
   };
 }
 
-const isBrowser$1 = typeof window !== 'undefined';
-const isServer$1 = !isBrowser$1;
+const isBrowser$2 = typeof window !== 'undefined';
+const isServer$2 = !isBrowser$2;
 const standardFacebookEvents = ['AddPaymentInfo', 'AddToCart', 'AddToWishlist', 'CompleteRegistration', 'Contact', 'CustomizeProduct', 'Donate', 'FindLocation', 'InitiateCheckout', 'Lead', 'Purchase', 'Schedule', 'Search', 'StartTrial', 'SubmitApplication', 'Subscribe', 'ViewContent', 'PageView'];
 /**
  * Create a Facebook Pixel integration instance
@@ -563,7 +563,7 @@ function createFacebookPixelIntegration(config) {
     name: 'facebook-pixel',
     environments: ['client'],
     init: () => __awaiter(this, void 0, void 0, function* () {
-      if (isServer$1) {
+      if (isServer$2) {
         // On server, Facebook Pixel is a no-op but doesn't throw
         // This allows the integration to be registered but remain inactive
         return;
@@ -642,6 +642,10 @@ function createFacebookPixelIntegration(config) {
           const amValues = coerceMetaConversionsAmValues(Object.assign(Object.assign({}, properties || {}), userId ? {
             external_id: userId
           } : {}));
+          // Advanced Matching
+          // Add event to identify user and hash email field
+          // FB pixel handles hashing automatically
+          // https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
           const am = {};
           if (amValues.external_id) am['external_id'] = amValues.external_id;
           if (amValues.em) am['em'] = sha256(amValues.em);
@@ -670,6 +674,18 @@ function getFacebookEventName(eventName, eventMapping) {
   if (!eventMapping) return eventName;
   return eventMapping[eventName] || eventName;
 }
+/**
+ * Get Advanced Matching values from properties
+ *
+ * Documentation for Pixel
+ * https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
+ *
+ * Documentation for Conversions API
+ * https://developers.secure.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+ *
+ * @param properties
+ * @returns
+ */
 function coerceMetaConversionsAmValues(properties) {
   const coerce = [{
     key: 'em',
@@ -777,6 +793,214 @@ function coerceMetaConversionsAmValues(properties) {
     }
   }];
   const result = {};
+  for (const {
+    key,
+    coerceFrom,
+    transform
+  } of coerce) {
+    const foundValue = findFirstProperty$1(properties, coerceFrom);
+    if (foundValue !== null && transform) {
+      const transformedValue = transform(foundValue);
+      if (transformedValue) {
+        result[key] = transformedValue;
+      }
+    } else if (foundValue !== null && typeof foundValue === 'string') {
+      result[key] = foundValue;
+    }
+  }
+  return result;
+}
+function findFirstProperty$1(properties, keys) {
+  for (const key of keys) {
+    if (properties[key] !== undefined) {
+      return properties[key];
+    }
+  }
+  return null;
+}
+
+/**
+ * TikTok Pixel Integration
+ *
+ * This integration provides TikTok Pixel tracking capabilities including:
+ * - Event tracking for standard and custom events
+ * - Advanced matching with hashed user identification data
+ * - Automatic script loading and initialization
+ *
+ * Key Resources:
+ * - Advanced Matching: https://business-api.tiktok.com/portal/docs?rid=5ipocbxyw8v&id=1739585700402178
+ * - Standard Events: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+const isBrowser$1 = typeof window !== 'undefined';
+const isServer$1 = !isBrowser$1;
+/**
+ * Standard TikTok events supported by the pixel
+ *
+ * Note: This list reflects TikTok's official standard events. Events like 'CompletePayment'
+ * are not standard events and should be tracked as custom events if needed.
+ *
+ * Documentation: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+const standardTikTokEvents = ['AddPaymentInfo', 'AddToCart', 'AddToWishlist', 'ApplicationApproval', 'CompleteRegistration', 'Contact', 'CustomizeProduct', 'Download', 'FindLocation', 'InitiateCheckout', 'Lead', 'Purchase', 'Schedule', 'Search', 'StartTrial', 'SubmitApplication', 'Subscribe', 'ViewContent', 'PageView'];
+/**
+ * Create a TikTok Pixel integration instance
+ */
+function createTikTokPixelIntegration(config) {
+  let isPixelReady = false;
+  return {
+    name: 'tiktok-pixel',
+    environments: ['client'],
+    init: () => __awaiter(this, void 0, void 0, function* () {
+      if (isServer$1) {
+        // On server, TikTok Pixel is a no-op but doesn't throw
+        // This allows the integration to be registered but remain inactive
+        return;
+      }
+      // Check if TikTok Pixel is already loaded
+      if (window.ttq) {
+        console.warn('TikTok Pixel is already initialized');
+        isPixelReady = true;
+        return;
+      }
+      // Initialize TikTok Pixel
+      return new Promise((resolve, reject) => {
+        try {
+          (function (w, d, t) {
+            w.TiktokAnalyticsObject = t;
+            const ttq = w[t] = w[t] || [];
+            ttq.methods = ['page', 'track', 'identify', 'instances', 'debug', 'on', 'off', 'once', 'ready', 'alias', 'group', 'enableCookie', 'disableCookie', 'holdConsent', 'revokeConsent', 'grantConsent'];
+            ttq.setAndDefer = function (t, e) {
+              t[e] = function () {
+                t.push([e].concat(Array.prototype.slice.call(arguments, 0)));
+              };
+            };
+            for (let i = 0; i < ttq.methods.length; i++) ttq.setAndDefer(ttq, ttq.methods[i]);
+            ttq.instance = function (t) {
+              const e = ttq._i[t] || [];
+              for (let n = 0; n < ttq.methods.length; n++) ttq.setAndDefer(e, ttq.methods[n]);
+              return e;
+            };
+            ttq.load = function (e, n) {
+              const r = 'https://analytics.tiktok.com/i18n/pixel/events.js';
+              const o = n && n.partner;
+              ttq._i = ttq._i || {};
+              ttq._i[e] = [];
+              ttq._i[e]._u = r;
+              ttq._t = ttq._t || {};
+              ttq._t[e] = +new Date();
+              ttq._o = ttq._o || {};
+              ttq._o[e] = n || {};
+              const script = document.createElement('script');
+              script.type = 'text/javascript';
+              script.async = true;
+              script.src = r + '?sdkid=' + e + '&lib=' + t;
+              // Add load event listener
+              script.onload = () => {
+                isPixelReady = true;
+                resolve();
+              };
+              script.onerror = () => {
+                reject(new Error('Failed to load TikTok Pixel script'));
+              };
+              const firstScript = document.getElementsByTagName('script')[0];
+              firstScript.parentNode.insertBefore(script, firstScript);
+            };
+            // Load the pixel with the provided ID
+            ttq.load(config.pixelId, config.testMode ? {
+              test_mode: true
+            } : undefined);
+            ttq.page();
+            // If script loads synchronously, mark as ready
+            if (window.ttq && typeof window.ttq === 'function') {
+              isPixelReady = true;
+              resolve();
+            }
+          })(window, document, 'ttq');
+        } catch (error) {
+          reject(error);
+        }
+      });
+    }),
+    track: (eventName, properties, context) => {
+      if (!isPixelReady || !window.ttq) return;
+      const ttEventName = getTikTokEventName(eventName, config.eventMapping);
+      // Handle PageView separately as it uses ttq.page()
+      if (ttEventName === 'PageView') {
+        window.ttq.page();
+        return;
+      }
+      // Map parameters based on specific event requirements
+      const ttParams = mapTikTokEventParameters(ttEventName, properties);
+      if (ttParams && Object.keys(ttParams).length > 0) {
+        window.ttq.track(ttEventName, ttParams);
+      } else {
+        window.ttq.track(ttEventName);
+      }
+    },
+    identify: (userId, properties, context) => {
+      try {
+        if (typeof window !== 'undefined' && window.ttq) {
+          const identifyData = coerceTikTokIdentifyValues(Object.assign(Object.assign({}, properties || {}), userId ? {
+            external_id: userId
+          } : {}));
+          if (Object.keys(identifyData).length > 0) {
+            window.ttq.identify(identifyData);
+          }
+        }
+      } catch (error) {
+        console.error('Error identifying user in TikTok Pixel:', error);
+      }
+    }
+  };
+}
+function getTikTokEventName(eventName, eventMapping) {
+  // Convert default saasco Page View event by default
+  if (eventName === 'Page View') return 'PageView';
+  if (!eventMapping) return eventName;
+  return eventMapping[eventName] || eventName;
+}
+/**
+ * Get identification values from properties for TikTok Pixel
+ *
+ * Advanced Matching Documentation:
+ * https://business-api.tiktok.com/portal/docs?rid=5ipocbxyw8v&id=1739585700402178
+ *
+ * Standard Events Documentation:
+ * https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ *
+ * @param properties
+ * @returns
+ */
+function coerceTikTokIdentifyValues(properties) {
+  const coerce = [{
+    key: 'email',
+    coerceFrom: ['email', 'user_email', 'userEmail', 'email_address', 'emailAddress', 'e_mail', 'E_Mail', 'mail', 'Mail', 'contact_email', 'contactEmail', 'primary_email', 'primaryEmail'],
+    transform: value => {
+      if (typeof value !== 'string') return undefined;
+      const normalized = value.trim().toLowerCase();
+      // TikTok requires hashed email
+      return normalized ? sha256(normalized) : undefined;
+    }
+  }, {
+    key: 'phone_number',
+    coerceFrom: ['phone', 'phone_number', 'phoneNumber', 'mobile', 'mobile_number', 'mobileNumber', 'contact_number', 'contactNumber', 'tel', 'telephone'],
+    transform: value => {
+      if (typeof value !== 'string' && typeof value !== 'number') return undefined;
+      const phoneStr = String(value).replace(/\D/g, '');
+      // TikTok requires hashed phone number
+      return phoneStr ? sha256(phoneStr) : undefined;
+    }
+  }, {
+    key: 'external_id',
+    coerceFrom: ['external_id', 'externalId', 'user_id', 'userId', 'id', 'distinctId', 'distinct_id', 'customer_id', 'customerId', 'member_id', 'memberId'],
+    transform: value => {
+      if (value == null) return undefined;
+      const stringValue = String(value);
+      // TikTok requires hashed external_id
+      return stringValue ? sha256(stringValue) : undefined;
+    }
+  }];
+  const result = {};
   for (const {
     key,
     coerceFrom,
@@ -802,6 +1026,63 @@ function findFirstProperty(properties, keys) {
   }
   return null;
 }
+/**
+ * Maps event properties to TikTok-specific parameters based on event type
+ *
+ * Parameter Documentation: https://ads.tiktok.com/help/article/about-parameters
+ * Standard Events: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+function mapTikTokEventParameters(eventName, properties) {
+  if (!properties) return null;
+  const params = {};
+  // Helper to safely add parameters, skipping objects/null/undefined
+  const addParam = (key, value) => {
+    if (value != null && typeof value !== 'object') {
+      params[key] = value;
+    }
+  };
+  switch (eventName) {
+    case 'AddToCart':
+    case 'Purchase':
+    case 'ViewContent':
+      addParam('content_type', properties['content_type']);
+      addParam('content_ids', properties['content_ids']);
+      addParam('quantity', properties['quantity']);
+      addParam('description', properties['description']);
+      addParam('currency', properties['currency']);
+      addParam('value', properties['value']);
+      addParam('content_name', properties['content_name']);
+      addParam('content_category', properties['content_category']);
+      break;
+    case 'StartTrial':
+      addParam('content_ids', properties['content_ids']);
+      addParam('currency', properties['currency']);
+      addParam('value', properties['value']);
+      break;
+    case 'Search':
+      const searchString = properties['search_string'] || properties['query'] || properties['search_query'];
+      addParam('search_string', searchString);
+      break;
+    case 'InitiateCheckout':
+    case 'AddPaymentInfo':
+      addParam('value', properties['value']);
+      addParam('currency', properties['currency']);
+      addParam('content_ids', properties['content_ids']);
+      addParam('quantity', properties['quantity']);
+      break;
+    case 'CompleteRegistration':
+    case 'Subscribe':
+      addParam('value', properties['value']);
+      addParam('currency', properties['currency']);
+      break;
+    default:
+      // Pass through common parameters for any other events
+      addParam('value', properties['value']);
+      addParam('currency', properties['currency']);
+      break;
+  }
+  return Object.keys(params).length > 0 ? params : null;
+}
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 class AnalyticsLogger {
@@ -1330,6 +1611,10 @@ class Saasco {
             this.logger.log('Registering Facebook Pixel integration with ID:', integrationConfig.config.pixelId);
             const fbIntegration = createFacebookPixelIntegration(integrationConfig.config);
             yield this.integrationManager.registerIntegration(fbIntegration);
+          } else if (integrationConfig.type === 'tiktok-pixel') {
+            this.logger.log('Registering TikTok Pixel integration with ID:', integrationConfig.config.pixelId);
+            const tiktokIntegration = createTikTokPixelIntegration(integrationConfig.config);
+            yield this.integrationManager.registerIntegration(tiktokIntegration);
           }
         } catch (error) {
           this.logger.log(`Failed to register ${integrationConfig.type} integration:`, error);
@@ -1590,4 +1875,4 @@ const browserContextSchema = z.object({
   $utmAdId: z.string().nullable()
 });
 
-export { IntegrationManager, Logger, Saasco, browserContextSchema, createFacebookPixelIntegration, getBrowserContext, standardFacebookEvents, timezones };
+export { IntegrationManager, Logger, Saasco, browserContextSchema, createFacebookPixelIntegration, createTikTokPixelIntegration, getBrowserContext, standardFacebookEvents, standardTikTokEvents, timezones };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasco-sdk",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "dependencies": {
     "tslib": "^2.3.0",
     "@lukeed/uuid": "^2.0.1",

package/src/lib/analytics.d.ts

@@ -1,4 +1,5 @@
 import { FacebookPixelIntegrationConfig } from './integrations/facebook-pixel';
+import { TikTokPixelIntegrationConfig } from './integrations/tiktok-pixel';
 declare global {
     interface Window {
         saascoAutoPageTrackingActive?: boolean;
@@ -29,7 +30,7 @@ export type IntegrationConfigBase = {
     type: string;
     config: Record<string, any>;
 };
-export type IntegrationsConfig = FacebookPixelIntegrationConfig[];
+export type IntegrationsConfig = (FacebookPixelIntegrationConfig | TikTokPixelIntegrationConfig)[];
 export declare class Saasco {
     private config;
     private lastPageViewPath;

package/src/lib/integrations/index.d.ts

@@ -1,2 +1,3 @@
 export * from './integration-manager';
 export * from './facebook-pixel';
+export * from './tiktok-pixel';

package/src/lib/integrations/tiktok-pixel.d.ts

@@ -0,0 +1,59 @@
+/**
+ * TikTok Pixel Integration
+ *
+ * This integration provides TikTok Pixel tracking capabilities including:
+ * - Event tracking for standard and custom events
+ * - Advanced matching with hashed user identification data
+ * - Automatic script loading and initialization
+ *
+ * Key Resources:
+ * - Advanced Matching: https://business-api.tiktok.com/portal/docs?rid=5ipocbxyw8v&id=1739585700402178
+ * - Standard Events: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+import { IntegrationConfigBase } from '../analytics';
+import { Integration } from './integration-manager';
+declare global {
+    interface Window {
+        ttq?: Ttq;
+        TiktokAnalyticsObject?: string;
+    }
+    interface Ttq {
+        (...args: any[]): void;
+        methods?: string[];
+        _i?: Record<string, any>;
+        _t?: Record<string, number>;
+        _o?: Record<string, any>;
+        load?: (pixelId: string, options?: any) => void;
+        page?: () => void;
+        track?: (eventName: string, properties?: Record<string, unknown>) => void;
+        identify?: (properties?: Record<string, unknown>) => void;
+        setAndDefer?: (obj: any, method: string) => void;
+        instance?: (pixelId: string) => any;
+    }
+}
+export type TikTokEventMapping = {
+    [key: string]: StandardTikTokEvent;
+};
+export type TikTokPixelIntegrationConfig = IntegrationConfigBase & {
+    type: 'tiktok-pixel';
+    config: TikTokPixelConfig;
+};
+export type TikTokPixelConfig = {
+    pixelId: string;
+    eventMapping?: TikTokEventMapping;
+    testMode?: boolean;
+};
+/**
+ * Standard TikTok events supported by the pixel
+ *
+ * Note: This list reflects TikTok's official standard events. Events like 'CompletePayment'
+ * are not standard events and should be tracked as custom events if needed.
+ *
+ * Documentation: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+export declare const standardTikTokEvents: readonly ["AddPaymentInfo", "AddToCart", "AddToWishlist", "ApplicationApproval", "CompleteRegistration", "Contact", "CustomizeProduct", "Download", "FindLocation", "InitiateCheckout", "Lead", "Purchase", "Schedule", "Search", "StartTrial", "SubmitApplication", "Subscribe", "ViewContent", "PageView"];
+export type StandardTikTokEvent = (typeof standardTikTokEvents)[number];
+/**
+ * Create a TikTok Pixel integration instance
+ */
+export declare function createTikTokPixelIntegration(config: TikTokPixelConfig): Integration;