@segment/analytics-browser-actions-tiktok-pixel 1.94.1-staging-108b283de.0 → 1.95.0

package/src/reportWebEvent/fields.ts

@@ -0,0 +1,162 @@
+import { InputField } from '@segment/actions-core'
+import { VEHICLE_FIELDS, TRAVEL_FIELDS } from '../constants'
+
+export const track_fields: Record<string, InputField> = {
+    event_spec_type: {
+        label: 'Additional Fields',
+        type: 'string',
+        description: 'Include fields for travel or vehicle events.',
+        choices: [
+        { value: TRAVEL_FIELDS, label: 'Travel Fields' },
+        { value: VEHICLE_FIELDS, label: 'Vehicle Fields' }
+        ]
+    },
+    event: {
+        label: 'Event Name',
+        type: 'string',
+        required: true,
+        description:
+        'Conversion event name. Please refer to the "Supported Web Events" section on in TikTok’s [Pixel SDK documentation](https://business-api.tiktok.com/portal/docs?id=1739585696931842) for accepted event names.'
+    },
+    event_id: {
+        label: 'Event ID',
+        type: 'string',
+        description: 'Any hashed ID that can identify a unique user/session.',
+        default: {
+        '@path': '$.messageId'
+        }
+    },
+    order_id: {
+        label: 'Order ID',
+        type: 'string',
+        description: 'Order ID of the transaction.',
+        default: {
+        '@path': '$.properties.order_id'
+        }
+    },
+    shop_id: {
+        label: 'Shop ID',
+        type: 'string',
+        description: 'Shop ID of the transaction.',
+        default: {
+        '@path': '$.properties.shop_id'
+        }
+    },
+    contents: {
+        label: 'Contents',
+        type: 'object',
+        multiple: true,
+        description: 'Related item details for the event.',
+        properties: {
+        price: {
+            label: 'Price',
+            description: 'Price of the item.',
+            type: 'number'
+        },
+        quantity: {
+            label: 'Quantity',
+            description: 'Number of items.',
+            type: 'number'
+        },
+        content_category: {
+            label: 'Content Category',
+            description: 'Category of the product item.',
+            type: 'string'
+        },
+        content_id: {
+            label: 'Content ID',
+            description: 'ID of the product item.',
+            type: 'string'
+        },
+        content_name: {
+            label: 'Content Name',
+            description: 'Name of the product item.',
+            type: 'string'
+        },
+        brand: {
+            label: 'Brand',
+            description: 'Brand name of the product item.',
+            type: 'string'
+        }
+        }
+    },
+    content_ids: {
+        label: 'Content IDs',
+        description:
+        "Product IDs associated with the event, such as SKUs. Do not populate this field if the 'Contents' field is populated. This field accepts a single string value or an array of string values.",
+        type: 'string',
+        multiple: true,
+        default: {
+        '@path': '$.properties.content_ids'
+        }
+    },
+    num_items: {
+        label: 'Number of Items',
+        type: 'number',
+        description: 'Number of items when checkout was initiated. Used with the InitiateCheckout event.',
+        default: {
+        '@path': '$.properties.num_items'
+        }
+    },
+    content_type: {
+        label: 'Content Type',
+        description:
+        'Type of the product item. When the `content_id` in the `Contents` field is specified as a `sku_id`, set this field to `product`. When the `content_id` in the `Contents` field is specified as an `item_group_id`, set this field to `product_group`.',
+        type: 'string',
+        choices: [
+        { label: 'product', value: 'product' },
+        { label: 'product_group', value: 'product_group' }
+        ],
+        default: 'product'
+    },
+    currency: {
+        label: 'Currency',
+        type: 'string',
+        description: 'Currency for the value specified as ISO 4217 code.',
+        default: {
+        '@path': '$.properties.currency'
+        }
+    },
+    value: {
+        label: 'Value',
+        type: 'number',
+        description: 'Value of the order or items sold.',
+        default: {
+        '@if': {
+            exists: { '@path': '$.properties.value' },
+            then: { '@path': '$.properties.value' },
+            else: { '@path': '$.properties.revenue' }
+        }
+        }
+    },
+    description: {
+        label: 'Description',
+        type: 'string',
+        description: 'A string description of the web event.'
+    },
+    query: {
+        label: 'Query',
+        type: 'string',
+        description: 'The text string that was searched for.',
+        default: {
+        '@path': '$.properties.query'
+        }
+    },
+    search_string: {
+        label: 'Search String',
+        type: 'string',
+        description: 'The text string entered by the user for the search. Optionally used with the Search event.',
+        default: {
+        '@path': '$.properties.search_string'
+        },
+        depends_on: {
+        conditions: [
+            {
+            fieldKey: 'event',
+            operator: 'is',
+            value: 'Search'
+            }
+        ]
+        }
+    }
+}

package/src/reportWebEvent/generated-types.ts

@@ -1,6 +1,10 @@
 // Generated file. DO NOT MODIFY IT BY HAND.
 
 export interface Payload {
+  /**
+   * Include fields for travel or vehicle events.
+   */
+  event_spec_type?: string
   /**
    * Conversion event name. Please refer to the "Supported Web Events" section on in TikTok’s [Pixel SDK documentation](https://business-api.tiktok.com/portal/docs?id=1739585696931842) for accepted event names.
    */
@@ -9,43 +13,6 @@ export interface Payload {
    * Any hashed ID that can identify a unique user/session.
    */
   event_id?: string
-  /**
-   * A single phone number in E.164 standard format. TikTok Pixel will hash this value before sending to TikTok. e.g. +14150000000. Segment will hash this value before sending to TikTok.
-   */
-  phone_number?: string[]
-  /**
-   * A single email address. TikTok Pixel will be hash this value before sending to TikTok.
-   */
-  email?: string[]
-  /**
-   * The first name of the customer. The name should be in lowercase without any punctuation. Special characters are allowed.
-   */
-  first_name?: string
-  /**
-   * The last name of the customer. The name should be in lowercase without any punctuation. Special characters are allowed.
-   */
-  last_name?: string
-  /**
-   * The address of the customer.
-   */
-  address?: {
-    /**
-     * The customer's city.
-     */
-    city?: string
-    /**
-     * The customer's country.
-     */
-    country?: string
-    /**
-     * The customer's Zip Code.
-     */
-    zip_code?: string
-    /**
-     * The customer's State.
-     */
-    state?: string
-  }
   /**
    * Order ID of the transaction.
    */
@@ -54,10 +21,6 @@ export interface Payload {
    * Shop ID of the transaction.
    */
   shop_id?: string
-  /**
-   * Uniquely identifies the user who triggered the conversion event. TikTok Pixel will hash this value before sending to TikTok.
-   */
-  external_id?: string[]
   /**
    * Related item details for the event.
    */
@@ -87,6 +50,14 @@ export interface Payload {
      */
     brand?: string
   }[]
+  /**
+   * Product IDs associated with the event, such as SKUs. Do not populate this field if the 'Contents' field is populated. This field accepts a single string value or an array of string values.
+   */
+  content_ids?: string[]
+  /**
+   * Number of items when checkout was initiated. Used with the InitiateCheckout event.
+   */
+  num_items?: number
   /**
    * Type of the product item. When the `content_id` in the `Contents` field is specified as a `sku_id`, set this field to `product`. When the `content_id` in the `Contents` field is specified as an `item_group_id`, set this field to `product_group`.
    */
@@ -107,4 +78,231 @@ export interface Payload {
    * The text string that was searched for.
    */
   query?: string
+  /**
+   * The text string entered by the user for the search. Optionally used with the Search event.
+   */
+  search_string?: string
+  /**
+   * A single phone number in E.164 standard format. TikTok Pixel will hash this value before sending to TikTok. e.g. +14150000000. Segment will hash this value before sending to TikTok.
+   */
+  phone_number?: string[]
+  /**
+   * A single email address. TikTok Pixel will be hash this value before sending to TikTok.
+   */
+  email?: string[]
+  /**
+   * The first name of the customer. The name should be in lowercase without any punctuation. Special characters are allowed.
+   */
+  first_name?: string
+  /**
+   * The last name of the customer. The name should be in lowercase without any punctuation. Special characters are allowed.
+   */
+  last_name?: string
+  /**
+   * The address of the customer.
+   */
+  address?: {
+    /**
+     * The customer's city.
+     */
+    city?: string
+    /**
+     * The customer's country.
+     */
+    country?: string
+    /**
+     * The customer's Zip Code.
+     */
+    zip_code?: string
+    /**
+     * The customer's State.
+     */
+    state?: string
+  }
+  /**
+   * Uniquely identifies the user who triggered the conversion event. TikTok Pixel will hash this value before sending to TikTok.
+   */
+  external_id?: string[]
+  /**
+   * Fields related to vehicle events.
+   */
+  vehicle_fields?: {
+    /**
+     * Postal code for the vehicle location.
+     */
+    postal_code?: string
+    /**
+     * Vehicle make/brand/manufacturer.
+     */
+    make?: string
+    /**
+     * Vehicle model.
+     */
+    model?: string
+    /**
+     * Year the vehicle was laucned in yyyy format.
+     */
+    year?: number
+    /**
+     * Vehicle status.
+     */
+    state_of_vehicle?: string
+    /**
+     * Vehicle mileage (in km or miles). Zero (0) for new vehicle.
+     */
+    mileage_value?: number
+    /**
+     * Mileage unites in miles (MI) or kilometers (KM).
+     */
+    mileage_unit?: string
+    /**
+     * Vehicle exterior color.
+     */
+    exterior_color?: string
+    /**
+     * Vehicle transmission type.
+     */
+    transmission?: string
+    /**
+     * Vehicle body type.
+     */
+    body_style?: string
+    /**
+     * Vehicle fuel type.
+     */
+    fuel_type?: string
+    /**
+     * Vehicle drivetrain.
+     */
+    drivetrain?: string
+    /**
+     * Minimum preferred price of the vehicle.
+     */
+    preferred_price_range_min?: number
+    /**
+     * Maximum preferred price of the vehicle.
+     */
+    preferred_price_range_max?: number
+    /**
+     * Vehicle trim.
+     */
+    trim?: string
+    /**
+     * Vehicle identification number. Maximum characters: 17.
+     */
+    vin?: string
+    /**
+     * Vehicle interior color.
+     */
+    interior_color?: string
+    /**
+     * Vehicle drivetrain.
+     */
+    condition_of_vehicle?: string
+    /**
+     * Optional for ViewContent. Use viewcontent_type to differentiate between soft lead landing pages.
+     */
+    viewcontent_type?: string
+    /**
+     * Optional for Search. Use search_type to differentiate other user searches (such as dealer lookup) from inventory search.
+     */
+    search_type?: string
+    /**
+     * Optional for CompleteRegistration. Use registration_type to differentiate between different types of customer registration on websites.
+     */
+    registration_type?: string
+  }
+  /**
+   * Fields related to travel events.
+   */
+  travel_fields?: {
+    /**
+     * Hotel city location.
+     */
+    city?: string
+    /**
+     * Hotel region location.
+     */
+    region?: string
+    /**
+     * Hotel country location.
+     */
+    country?: string
+    /**
+     * Hotel check-in date.
+     */
+    checkin_date?: string
+    /**
+     * Hotel check-out date.
+     */
+    checkout_date?: string
+    /**
+     * Number of adults.
+     */
+    num_adults?: number
+    /**
+     * Number of children.
+     */
+    num_children?: number
+    /**
+     * Number of infants flying.
+     */
+    num_infants?: number
+    /**
+     * Suggested hotels. This can be a single string value or an array of string values.
+     */
+    suggested_hotels?: string[]
+    /**
+     * Date of flight departure. Accepted date formats: YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD, and YYYY-MM-DDThh:mm:ssTZD
+     */
+    departing_departure_date?: string
+    /**
+     * Date of return flight. Accepted date formats: YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD, and YYYY-MM-DDThh:mm:ssTZD
+     */
+    returning_departure_date?: string
+    /**
+     * Origin airport.
+     */
+    origin_airport?: string
+    /**
+     * Destination airport.
+     */
+    destination_airport?: string
+    /**
+     * If a client has a destination catalog, the client can associate one or more destinations in the catalog with a specific flight event. For instance, link a particular route to a nearby museum and a nearby beach, both of which are destinations in the catalog. This field accepts a single string value or an array of string values.
+     */
+    destination_ids?: string[]
+    /**
+     * The date and time for arrival at the destination of the outbound journey. Accepted date formats: YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD, and YYYY-MM-DDThh:mm:ssTZD
+     */
+    departing_arrival_date?: string
+    /**
+     * The date and time when the return journey is completed. Accepted date formats: YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD, and YYYY-MM-DDThh:mm:ssTZD
+     */
+    returning_arrival_date?: string
+    /**
+     * Class of the flight ticket, must be: "eco", "prem", "bus", "first".
+     */
+    travel_class?: string
+    /**
+     * Represents the relative value of this potential customer to advertiser.
+     */
+    user_score?: number
+    /**
+     * The preferred number of stops the user is looking for. 0 for direct flight.
+     */
+    preferred_num_stops?: number
+    /**
+     * The start date of user's trip. Accept date formats: YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD, and YYYY-MM-DDThh:mm:ssTZD.
+     */
+    travel_start?: string
+    /**
+     * The end date of user's trip. Accept date formats: YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD, and YYYY-MM-DDThh:mm:ssTZD.
+     */
+    travel_end?: string
+    /**
+     * A list of IDs representing destination suggestions for this user. This parameter is not applicable for the Search event. This field accepts a single string value or an array of string values.
+     */
+    suggested_destinations?: string[]
+  }
 }

package/src/reportWebEvent/index.ts

@@ -1,9 +1,13 @@
 import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
 import type { Settings } from '../generated-types'
 import type { Payload } from './generated-types'
-import { formatPhone, handleArrayInput, formatString, formatAddress } from '../formatter'
+import { getUser } from '../utils'
+import { getAllProperties } from './utils'
 import { TikTokPixel } from '../types'
-import { commonFields } from '../common_fields'
+import { track_fields } from './fields'
+import { common_fields } from '../fields/common_fields'
+import { travel_fields } from './travel_fields'
+import { vehicle_fields } from './vehicle_fields'
 
 const action: BrowserActionDefinition<Settings, TikTokPixel, Payload> = {
   title: 'Report Web Event',
@@ -12,36 +16,20 @@ const action: BrowserActionDefinition<Settings, TikTokPixel, Payload> = {
   platform: 'web',
   defaultSubscription: 'type = "track"',
   fields: {
-    ...commonFields
+    ...track_fields,
+    ...common_fields,
+    vehicle_fields,
+    travel_fields
   },
   perform: (ttq, { payload, settings }) => {
     if (payload.email || payload.phone_number || payload.external_id) {
-      ttq.identify({
-        email: handleArrayInput(payload.email),
-        phone_number: formatPhone(handleArrayInput(payload.phone_number)),
-        external_id: handleArrayInput(payload.external_id),
-        first_name: formatString(payload.first_name),
-        last_name: formatString(payload.last_name),
-        city: formatAddress(payload.address?.city),
-        state: formatAddress(payload.address?.state),
-        country: formatAddress(payload.address?.country),
-        zip_code: formatString(payload.address?.zip_code)
-      })
+      ttq.instance(settings.pixelCode).identify(getUser(payload))
     }
 
     ttq.instance(settings.pixelCode).track(
-      payload.event,
-      {
-        contents: payload.contents ? payload.contents : [],
-        content_type: payload.content_type ? payload.content_type : undefined,
-        currency: payload.currency ? payload.currency : 'USD',
-        value: payload.value || payload.value === 0 ? payload.value : undefined,
-        query: payload.query ? payload.query : undefined,
-        description: payload.description ? payload.description : undefined,
-        order_id: payload.order_id ? payload.order_id : undefined,
-        shop_id: payload.shop_id ? payload.shop_id : undefined
-      },
-      {
+      payload.event, 
+      getAllProperties(payload), 
+      { 
         event_id: payload.event_id ? payload.event_id : ''
       }
     )