STRATCONN-6081 - [TikTok Conversions] - CRM support

packages/destination-actions/src/destinations/tiktok-conversions/__tests__/formatter.test.ts

@@ -1,4 +1,4 @@
-import { formatEmails, formatPhones } from '../formatter'
+import { formatEmails, formatPhones } from '../reportWebEvent/formatter'
 
 describe('Tiktok Conversions Formatter', () => {
   describe('formatEmails', () => {

packages/destination-actions/src/destinations/tiktok-conversions/__tests__/index.test.ts

@@ -436,7 +436,6 @@ describe('Tiktok Conversions', () => {
         properties: {
           email: '[email protected]',
           phone: '+1555-555-5555',
-          lead_id: '2229012621312',
           currency: 'USD',
           value: 100,
           query: 'shoes',
@@ -527,7 +526,6 @@ describe('Tiktok Conversions', () => {
               email: ['eb9869a32b532840dd6aa714f7a872d21d6f650fc5aa933d9feefc64708969c7'],
               external_id: ['481f202262e9c5ccc48d24e60798fadaa5f6ff1f8369f7ab927c04c3aa682a7f'],
               ip: '0.0.0.0',
-              lead_id: '2229012621312',
               phone: ['910a625c4ba147b544e6bd2f267e130ae14c591b6ba9c25cb8573322dedbebd0'],
               ttclid: '123ATXSfe',
               user_agent:
@@ -573,45 +571,7 @@ describe('Tiktok Conversions', () => {
         userId: 'testId123'
       })
 
-      nock('https://business-api.tiktok.com/open_api/v1.3/event/track').post('/').reply(200, {})
-      const responses = await testDestination.testAction('reportWebEvent', {
-        event,
-        settings,
-        useDefaultMappings: true,
-        mapping: {
-          event: 'AddToCart',
-          test_event_code: 'TEST04030',
-          contents: {
-            '@arrayPath': [
-              '$.properties',
-              {
-                price: {
-                  '@path': '$.price'
-                },
-                quantity: {
-                  '@path': '$.quantity'
-                },
-                content_category: {
-                  '@path': '$.category'
-                },
-                content_id: {
-                  '@path': '$.product_id'
-                },
-                content_name: {
-                  '@path': '$.name'
-                },
-                brand: {
-                  '@path': '$.brand'
-                }
-              }
-            ]
-          }
-        }
-      })
-
-      expect(responses.length).toBe(1)
-      expect(responses[0].status).toBe(200)
-      expect(responses[0].options.json).toMatchObject({
+      const json = {
         data: [
           {
             event: 'AddToCart',
@@ -653,7 +613,46 @@ describe('Tiktok Conversions', () => {
         event_source_id: 'test',
         partner_name: 'Segment',
         test_event_code: 'TEST04030'
+      }
+
+      nock('https://business-api.tiktok.com/open_api/v1.3/event/track').post('/', json).reply(200, {})
+      const responses = await testDestination.testAction('reportWebEvent', {
+        event,
+        settings,
+        useDefaultMappings: true,
+        mapping: {
+          event: 'AddToCart',
+          test_event_code: 'TEST04030',
+          contents: {
+            '@arrayPath': [
+              '$.properties',
+              {
+                price: {
+                  '@path': '$.price'
+                },
+                quantity: {
+                  '@path': '$.quantity'
+                },
+                content_category: {
+                  '@path': '$.category'
+                },
+                content_id: {
+                  '@path': '$.product_id'
+                },
+                content_name: {
+                  '@path': '$.name'
+                },
+                brand: {
+                  '@path': '$.brand'
+                }
+              }
+            ]
+          }
+        }
       })
+
+      expect(responses.length).toBe(1)
+      expect(responses[0].status).toBe(200)
     })
   })
 })

packages/destination-actions/src/destinations/tiktok-conversions/index.ts

@@ -1,7 +1,6 @@
 import type { DestinationDefinition } from '@segment/actions-core'
 import { defaultValues } from '@segment/actions-core'
 import type { Settings } from './generated-types'
-
 import reportWebEvent from './reportWebEvent'
 
 const productProperties = {

packages/destination-actions/src/destinations/tiktok-conversions/reportWebEvent/constants.ts

@@ -0,0 +1,4 @@
+export const VEHICLE_FIELDS = 'vehicle_fields'
+export const TRAVEL_FIELDS = 'travel_fields'
+export const WEB = 'web'
+export const CRM = 'crm'

packages/destination-actions/src/destinations/tiktok-conversions/common_fields.ts → packages/destination-actions/src/destinations/tiktok-conversions/reportWebEvent/fields/common_fields.ts

@@ -1,6 +1,33 @@
 import { InputField } from '@segment/actions-core'
+import { VEHICLE_FIELDS, TRAVEL_FIELDS, WEB, CRM } from '../constants'
 
-export const commonFields: Record<string, InputField> = {
+export const common_fields: Record<string, InputField> = {
+  event_source: {
+    label: 'Event Source',
+    type: 'string',
+    description:
+      "The type of events you are uploading through TikTok Events API. Please see TikTok's [Events API documentation](https://ads.tiktok.com/marketing_api/docs?id=1701890979375106) for information on how to find this value. If no selection is made 'Web' is assumed.",
+    default: WEB,
+    choices: [
+      {
+        value: WEB,
+        label: 'The events took place on your website and are measured by a Pixel Code.'
+      },
+      {
+        value: CRM,
+        label: 'The lead events took place on a CRM system and are tracked by a CRM Event Set ID.'
+      }
+    ]
+  },
+  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',
@@ -36,8 +63,7 @@ export const commonFields: Record<string, InputField> = {
         then: { '@path': '$.properties.phone' },
         else: { '@path': '$.context.traits.phone' }
       }
-    },
-    category: 'hashedPII'
+    }
   },
   email: {
     label: 'Email',
@@ -51,8 +77,7 @@ export const commonFields: Record<string, InputField> = {
         then: { '@path': '$.properties.email' },
         else: { '@path': '$.context.traits.email' }
       }
-    },
-    category: 'hashedPII'
+    }
   },
   first_name: {
     label: 'First Name',
@@ -65,8 +90,7 @@ export const commonFields: Record<string, InputField> = {
         then: { '@path': '$.properties.first_name' },
         else: { '@path': '$.context.traits.first_name' }
       }
-    },
-    category: 'hashedPII'
+    }
   },
   last_name: {
     label: 'Last Name',
@@ -79,8 +103,7 @@ export const commonFields: Record<string, InputField> = {
         then: { '@path': '$.properties.last_name' },
         else: { '@path': '$.context.traits.last_name' }
       }
-    },
-    category: 'hashedPII'
+    }
   },
   address: {
     label: 'Address',
@@ -101,8 +124,7 @@ export const commonFields: Record<string, InputField> = {
       zip_code: {
         label: 'Zip Code',
         type: 'string',
-        description: "The customer's Zip Code.",
-        category: 'hashedPII'
+        description: "The customer's Zip Code."
       },
       state: {
         label: 'State',
@@ -169,8 +191,7 @@ export const commonFields: Record<string, InputField> = {
         then: { '@path': '$.userId' },
         else: { '@path': '$.anonymousId' }
       }
-    },
-    category: 'hashedPII'
+    }
   },
   ttclid: {
     label: 'TikTok Click ID',
@@ -198,13 +219,6 @@ export const commonFields: Record<string, InputField> = {
       }
     }
   },
-  lead_id: {
-    label: 'TikTok Lead ID',
-    description:
-      'ID of TikTok leads. Every lead will have its own lead_id when exported from TikTok. This feature is in Beta. Please contact your TikTok representative to inquire regarding availability',
-    type: 'string',
-    default: { '@path': '$.properties.lead_id' }
-  },
   locale: {
     label: 'Locale',
     description:
@@ -251,7 +265,6 @@ export const commonFields: Record<string, InputField> = {
     type: 'object',
     multiple: true,
     description: 'Related item details for the event.',
-    defaultObjectUI: 'keyvalue',
     properties: {
       price: {
         label: 'Price',
@@ -285,6 +298,23 @@ export const commonFields: Record<string, InputField> = {
       }
     }
   },
+  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:
@@ -343,5 +373,44 @@ export const commonFields: Record<string, InputField> = {
     type: 'string',
     description:
       'Use this field to specify that events should be test events rather than actual traffic. You can find your Test Event Code in your TikTok Events Manager under the "Test Event" tab. You\'ll want to remove your Test Event Code when sending real traffic through this integration.'
+  },
+  delivery_category: {
+    label: 'Delivery Category',
+    type: 'string',
+    description: 'Category of the delivery.',
+    default: {
+      '@path': '$.properties.delivery_category'
+    },
+    choices: [
+      { value: 'in_store', label: 'In Store - Purchase requires customer to enter the store.' },
+      { value: 'curbside', label: 'Curbside - Purchase requires curbside pickup.' },
+      { value: 'home_delivery', label: 'Home Delivery - Purchase is delivered to the customer.' }
+    ]
+  },
+  predicted_ltv: {
+    label: 'Prediected Lifetime Value',
+    type: 'number',
+    description:
+      'Predicted lifetime value of a subscriber as defined by the advertiser and expressed as an exact value.',
+    default: {
+      '@path': '$.properties.predicted_ltv'
+    }
+  },
+  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'
+        }
+      ]
+    }
   }
 }

packages/destination-actions/src/destinations/tiktok-conversions/reportWebEvent/fields/crm_fields.ts

@@ -0,0 +1,48 @@
+import { InputField } from '@segment/actions-core'
+import { CRM } from '../constants'
+
+export const crm_fields: Record<string, InputField> = {
+  lead_fields: {
+    label: 'CRM Fields',
+    type: 'object',
+    description: 'Fields related to CRM events.',
+    additionalProperties: false,
+    defaultObjectUI: 'keyvalue',
+    properties: {
+      lead_id: {
+        label: 'TikTok Lead ID',
+        description:
+          'ID of TikTok leads. Every lead will have its own lead_id when exported from TikTok. This feature is in Beta. Please contact your TikTok representative to inquire regarding availability',
+        type: 'string'
+      },
+      lead_event_source: {
+        label: 'TikTok Lead Event Source',
+        description:
+          'Lead source of TikTok leads. Please set this field to the name of your CRM system, such as HubSpot or Salesforce.',
+        type: 'string'
+      }
+    },
+    default: {
+      lead_id: { '@path': '$.properties.lead_id' },
+      lead_event_source: { '@path': '$.properties.lead_event_source' }
+    },
+    required: {
+      conditions: [
+        {
+          fieldKey: 'event_source',
+          operator: 'is',
+          value: CRM
+        }
+      ]
+    },
+    depends_on: {
+      conditions: [
+        {
+          fieldKey: 'event_source',
+          operator: 'is',
+          value: CRM
+        }
+      ]
+    }
+  }
+}