Skip to content

1. Destination Specification

Jump to bottom
Caio Tomazelli edited this page Jul 12, 2024 · 10 revisions

Destinations are composed of two different sets of specifications:

  • Configuration (or metadata): Provided as a JSON config (or through the Destination creation wizard at 1PD Scheduler. This set of fields consists of authentication, scope and description information that are used for all data sent through the destination at hand.

  • Data schema: This is the actual data that is sent through the destination. Each row can have a different value of each one of these columns. Example datasets using corresponding schema can be found at the sample_data folder

CM360 OCI

Config

Name Type Description
profile_id str A Campaign Manager Profile ID.
encryptionEntityType str The encryption entity type.
encryptionEntityId str The encryption entity ID.
encryptionEntitySource str Whether the encrypted cookie was received from ad serving or from Data Transfer.
kind str Identifies what kind of resource this is.
access_token str A Campaign Manager 360 access token.
refresh_token str A Campaign Manager 360 API refresh token.
token_uri str A Campaign Manager 360 API token uri.
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.

Data Schema

More information on CM360 OCI Documentation

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
floodlightConfigurationId true str Floodlight Configuration ID of this conversion.
floodlightActivityId true str Floodlight Activity ID of this conversion.
timestamp_micros true str The timestamp of conversion, in Unix epoch micros.
ordinal true str The ordinal of the conversion. Use this field to control how conversions of the same user and day are de-duplicated. This is a required field.
value false number The value of the conversion.
quantity false number The quantity of the conversion.
limitAdTracking false boolean Whether Limit Ad Tracking is enabled. When set to true, the conversion will be used for reporting but not targeting. This will prevent remarketing.
childDirectedTreatment false boolean Whether this particular request may come from a user under the age of 13, under COPPA compliance.
nonPersonalizedAd false boolean Whether the conversion was for a non personalized ad.
treatmentForUnderage false boolean Whether this particular request may come from a user under the age of 16 (may differ by country), under compliance with the European Union's General Data Protection Regulation (GDPR).
encryptedUserId false* str The alphanumeric encrypted user ID.
mobileDeviceId false* str The mobile device ID.
gclid false* str The Google click ID (gclid) associated with this conversion.
dclid false* str The timestamp of conversion, in Unix epoch micros
matchId false* str The match ID field. A match ID is your own first-party identifier that has been synced with Google using the match ID feature in Floodlight.
  • *: At least one of gclid, dclid, encryptedUserId, mobileDeviceId or matchId must be provided per row.

DV360 Customer Match

Config

Name Type Description
advertiser_id str A DV360 Advertiser ID.
audience_name str The display name of the audience list.
payload_type Enum["Contact_Info", "Device_Id"] DV360 Customer Match Payload Type
app_id str An app Id that matches with the type of the mobileDeviceIds being uploaded.
membership_duration_days int The duration in days that an entry remains in the audience after the qualifying event.
access_token str An OAuth2.0 access token.
refresh_token str An Oauth2.0 refresh token.
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.

Data Schema

More information on DV360 Customer Match Documentation

Contact Info fields

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
email false str Unhashed email of the member. Remove all whitespace and make sure the string is all lowercase.
hashed_email false str Hashed email of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
phone_number false str Unhashed phone number of the member. All phone numbers must be formatted using the (E.164)[https://en.wikipedia.org/wiki/E.164] format and include the country calling code.
hashed_phone_number false str Hashed phone number of the member. Before hashing, all phone numbers must be formatted using the (E.164)[https://en.wikipedia.org/wiki/E.164] format and include the country calling code.
first_name false str Unhashed first name of the member. Remove all whitespace and make sure the string is all lowercase.
hashed_first_name false str Hashed first name of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
last_name false str Unhashed last name of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
hashed_last_name false str Hashed first name of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
zip_code false str Unhashed zip code of the member.
country_code false str Unhashed country code of the member.
  • *: When the hashed version of an identifier is present, it's unhashed version is ignored
  • **: At least one identifier is needed.
  • ***: If one of the address fields is provided, all of them need to be provided. More details here.

Device Id Fields

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
mobile_device_id true str Mobile device id of the member.

Consent Fields

Column name Required type Description
ad_user_data_consent false str Represents consent for ad user data. Should be one of 'GRANTED' or 'DENIED'.
ad_personalization_consent false str Represents consent for ad personalization. Should be one of 'GRANTED' or 'DENIED'.

GA4MP

Config

Name Type Description
api_secret str An API SECRET generated in the Google Analytics UI.
payload_type Enum["gtag", "firebase"] GA4 client type.
measurement_id str The measurement ID associated with a stream. Found in the Google Analytics UI.
firebase_app_id str The Firebase App ID. The identifier for a Firebase app. Found in the Firebase console.
non_personalized_ads bool Set to true to indicate these events should not be used for personalized ads.
debug bool Dry-run (validation mode).
user_properties List[objects] The user properties for the measurement.

Data Schema

More information on GA4 Measurement Protocol Documentation

Common columns

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
event_name true str The name of the event being sent (one event per row)
user_id false str Optional GA4 unique identifier for a user
timestamp_micros false str Optional. A Unix timestamp (in microseconds) for the time to associate with the event. This should only be set to record events that happened in the past. This value can be overridden via user_property or event timestamps. Events can be backdated up to 3 calendar days based on the property's timezone.

App-specific

Column name Required Description
app_instance_id true A unique identifier for a Firebase app instance.

Web-specific

Column name Required Description
client_id true A unique identifier for a client.

Other fields

All other fields will be considered event parameters. For now, we only support the recommended parameters for each kind of event described below and documented here.

  "achievement_id",
  "campaign",
  "campaign_id",
  "character",
  "content",
  "content_id",
  "content_type",
  "coupon",
  "creative_name",
  "creative_slot",
  "currency",
  "engagement_time_msec",
  "group_id",
  "item_id",
  "item_list_id",
  "item_list_name",
  "item_name",
  "items",
  "level",
  "medium",
  "method",
  "payment_type",
  "promotion_id",
  "promotion_name",
  "score",
  "search_term",
  "shipping",
  "shipping_tier",
  "source",
  "tax",
  "term",
  "transaction_id",
  "value",
  "virtual_currency_name",
  "session_id"

Google Ads Customer Match

Config

Name Type Description
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.
developer_token str A Google Ads Developer Token.
login_customer_id str A Google Ads Login Customer ID (without hyphens).
refresh_token str A Google Ads API refresh token.
user_list_id str ID of the user list this destination will add users to.

Data Schema

More information on Google Ads Customer Match Documentation

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
email false str Unhashed email of the member. Remove all whitespace and make sure the string is all lowercase.
phone_number false str Unhashed phone number of the member. All phone numbers must be formatted using the (E.164)[https://en.wikipedia.org/wiki/E.164] format and include the country calling code.
first_name false str Unhashed first name of the member. Remove all whitespace and make sure the string is all lowercase.
last_name false str Unhashed last name of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
zip_code false str Unhashed zip code of the member.
country_code false str Unhashed country code of the member.
  • *: At least one identifier is needed.
  • **: If one of the address fields is provided, all of them need to be provided. More details here.

Consent Fields

Column name Required type Description
ad_user_data_consent false str Represents consent for ad user data. Should be one of 'GRANTED' or 'DENIED'.
ad_personalization_consent false str Represents consent for ad personalization. Should be one of 'GRANTED' or 'DENIED'.

Google Ads EC for Leads

Config

Name Type Description
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.
developer_token str A Google Ads Developer Token.
login_customer_id str A Google Ads Login Customer ID (without hyphens).
refresh_token str A Google Ads API refresh token.

Data Schema

More information on Google Ads EC For Leads Documentation

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
customer_id true str The ID of the customer performing the upload.
conversion_action_id true str Resource id of the conversion action associated with this conversion.
conversion_date_time true str The date time at which the conversion occurred. Must be after the click time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+
conversion_value true number The value of the conversion for the advertiser.
email false str Raw email (this is hashed before Tightlock sends the request). Ignored if hashed_email is provided.
phone_number false str Raw phone_number (this is hashed before Tightlock sends the request). Ignored if hashed_phone_number is provided.
hashed_email false str Hashed email address using SHA-256 hash function after normalization.
hashed_phone_number false str Hashed phone number using SHA-256 hash function after normalization (E164 standard).
order_id false str The order ID associated with the conversion. An order id can only be used for one conversion per conversion action.
currency_code false (Defaults to USD) str Currency associated with the conversion value. This is the ISO 4217 3-character currency code. For example: USD, EUR.
conversion_custom_variable_id false str Resource name of the custom variable associated with this conversion.
conversion_custom_variable_value false str The value string of this custom variable. The value of the custom variable should not contain private customer data, such as email addresses or phone numbers.

Consent Fields

Column name Required type Description
ad_user_data_consent false str Represents consent for ad user data. Should be one of 'GRANTED' or 'DENIED'.
ad_personalization_consent false str Represents consent for ad personalization. Should be one of 'GRANTED' or 'DENIED'.

Google Ads EC for Web

Config

Name Type Description
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.
developer_token str A Google Ads Developer Token.
login_customer_id str A Google Ads Login Customer ID (without hyphens).
refresh_token str A Google Ads API refresh token.

Data Schema

More information on EC For Web Documentation

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
customer_id true str The ID of the customer performing the upload.
conversion_action_id true str Resource id of the conversion action associated with this conversion.
order_id true str The order ID associated with the conversion. An order id can only be used for one conversion per conversion action.
gclid false str Google click ID (gclid) associated with the original conversion for this adjustment. Must be accompanied by conversion_date_time.
conversion_date_time false str The date time at which the original conversion for this adjustment occurred. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+
user_agent false str The user agent to enhance the original conversion. This can be found in your user's HTTP request header when they convert on your web page.
email false str Unhashed email of the member. Remove all whitespace and make sure the string is all lowercase.
hashed_email false str Hashed email of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
phone_number false str Unhashed phone number of the member. All phone numbers must be formatted using the (E.164)[https://en.wikipedia.org/wiki/E.164] format and include the country calling code.
hashed_phone_number false str Hashed phone number of the member. Before hashing, all phone numbers must be formatted using the (E.164)[https://en.wikipedia.org/wiki/E.164] format and include the country calling code.
first_name false str Unhashed first name of the member. Remove all whitespace and make sure the string is all lowercase.
hashed_first_name false str Hashed first name of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
last_name false str Unhashed last name of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
hashed_last_name false str Hashed first name of the member. Before hashing, remove all whitespace and make sure the string is all lowercase.
zip_code false str Unhashed zip code of the member.
country_code false str Unhashed country code of the member.
  • *: When the hashed version of an identifier is present, it's unhashed version is ignored
  • **: At least one identifier is needed.
  • ***: If one of the address fields is provided, all of them need to be provided. More details here.

Google Ads Conversion Adjustments

Config

Name Type Description
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.
developer_token str A Google Ads Developer Token.
login_customer_id str A Google Ads Login Customer ID (without hyphens).
refresh_token str A Google Ads API refresh token.

Data Schema

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
customer_id true str The ID of the customer performing the upload.
conversion_action_id true str Resource id of the conversion action associated with this conversion.
adjustment_date_time true str The date time at which the adjustment occurred. Must be after the click time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+
adjusted_value true number The restated conversion value. This is the value of the conversion after restatement. For example, to change the value of a conversion from 100 to 70, an adjusted value of 70 should be reported.
gclid false str Google click ID (gclid) associated with the original conversion for this adjustment. Must be accompanied by conversion_date_time.
conversion_date_time false str The date time at which the original conversion for this adjustment occurred. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+
currency_code false (Defaults to USD) str Currency associated with the conversion value. This is the ISO 4217 3-character currency code. For example: USD, EUR.
order_id false str The order ID associated with the conversion. An order id can only be used for one conversion per conversion action.

Google Ads OCI

Config

Name Type Description
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.
developer_token str A Google Ads Developer Token.
login_customer_id str A Google Ads Login Customer ID (without hyphens).
refresh_token str A Google Ads API refresh token.

Data Schema

More information on Google Ads OCI Documentation

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
customer_id true str Identifies the Google Ads account of your upload. Set this to the Google Ads conversion customer of the account that is the source of the clicks.
conversion_action_id true str Resource name of the conversion action associated with this conversion.
conversion_date_time true str The date time at which the conversion occurred. Must be after the click time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+
conversion_value true number The value of the conversion for the advertiser.
gclid false* str The Google click ID (gclid) associated with this conversion.
gbraid false* str The click identifier for clicks associated with app conversions and originating from iOS devices starting with iOS14.
wbraid false* str The click identifier for clicks associated with web conversions and originating from iOS devices starting with iOS14.
currency_code false (Defaults to USD) str Currency associated with the conversion value. This is the ISO 4217 3-character currency code. For example: USD, EUR.
conversion_custom_variable_id false str Resource name of the custom variable associated with this conversion.
conversion_custom_variable_value false str The value string of this custom variable. The value of the custom variable should not contain private customer data, such as email addresses or phone numbers.
  • *: At least one of gclid, gbraid or wbraid must be provided per row.

Consent Fields

Column name Required type Description
ad_user_data_consent false str Represents consent for ad user data. Should be one of 'GRANTED' or 'DENIED'.
ad_personalization_consent false str Represents consent for ad personalization. Should be one of 'GRANTED' or 'DENIED'.

Google Ads SSI

Config

Name Type Description
client_id str An OAuth2.0 Web Client ID.
client_secret str An OAuth2.0 Web Client Secret.
developer_token str A Google Ads Developer Token.
login_customer_id str A Google Ads Login Customer ID (without hyphens).
refresh_token str A Google Ads API refresh token.

Data Schema

More information on Google Ads SSI

Column name Required type Description
id true str Unique identifier required by Tightlock, used for internal processing only (not used by the final destination). Must be populated with non-repeating values. The field name can be customized when creating the source, see source specification for more details.
customer_id true str The ID of the customer performing the upload.
conversion_action_id true str Resource id of the conversion action associated with this conversion.
conversion_date_time true str The date time at which the conversion occurred. Must be after the click time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+
conversion_micro_value true number Transaction amount in micros. Transaction amount in micros needs to be greater than 1000.
email false str Raw email (this is hashed before Tightlock sends the request). Ignored if hashed_email is provided.
phone_number false str Raw phone_number (this is hashed before Tightlock sends the request). Ignored if hashed_phone_number is provided.
hashed_email false str Hashed email address using SHA-256 hash function after normalization.
hashed_phone_number false str Hashed phone number using SHA-256 hash function after normalization (E164 standard).
first_name false str Unhashed first name. Remove all whitespace and make sure the string is all lowercase.
hashed_first_name false str Hashed first name. Before hashing, remove all whitespace and make sure the string is all lowercase.
last_name false str Unhashed last name. Before hashing, remove all whitespace and make sure the string is all lowercase.
hashed_last_name false str Hashed first name. Before hashing, remove all whitespace and make sure the string is all lowercase.
zip_code false str Unhashed zip code.
country_code false str Unhashed country code.
state false str Unhashed state.
city false str Unhashed city.
external_id false str User specified job ID.
currency_code false (Defaults to USD) str Currency associated with the conversion value. This is the ISO 4217 3-character currency code. For example: USD, EUR.
custom_key false str Name of the store sales custom variable key. A predefined key that can be applied to the transaction and then later used for custom segmentation in reporting. Accessible only to customers on the allow-list.
custom_value false str Value of the custom variable for each transaction. Accessible only to customers on the allow-list.

Consent Fields

Column name Required type Description
ad_user_data_consent false str Represents consent for ad user data. Should be one of 'GRANTED' or 'DENIED'.
ad_personalization_consent false str Represents consent for ad personalization. Should be one of 'GRANTED' or 'DENIED'.
Clone this wiki locally