-
Notifications
You must be signed in to change notification settings - Fork 15
1. Destination Specification
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
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. |
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.
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. |
More information on DV360 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. |
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.
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. |
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'. |
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. |
More information on GA4 Measurement Protocol 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. |
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. |
Column name | Required | Description |
---|---|---|
app_instance_id | true | A unique identifier for a Firebase app instance. |
Column name | Required | Description |
---|---|---|
client_id | true | A unique identifier for a client. |
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"
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. |
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. |
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.
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'. |
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. |
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. |
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. |
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'. |
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. |
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. |
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.
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. |
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. |
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. |
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.
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'. |
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. |
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. |
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. |
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'. |