You are here:
JSON Metadata Usage and Examples for External Activation Platforms
Here are the JSON examples followed by the field descriptions and best practices to help you define your external activation platform.
Sample JSON for Output Grouping by PER_USER
{
{
"name": "abc-user-identifiers",
"apiName": "abc_user_identifiers",
"description": "Activation platform to activate only user identifiers",
"platformType": "Advertising",
"outputGrouping": "PER_USER",
"refreshFrequency": "TWENTY_FOUR",
"refreshMode": "FULL",
"connector": {
"connectorType": "S3",
"bucketName": "example-uswest2-cdp001-sample-data",
"exportDirectory": "datacloud-activations"
},
"activationAttributes": [
{
"displayName": "Hashed Email",
"destinationName": "EmailAddress",
"objectName": "ContactPointEmail",
"fieldName": "Email",
"isRequired": true,
"applyHash": true,
"isIdentifier": true
},
{
"displayName": "Hashed Phone",
"destinationName": "PhoneNumber",
"objectName": "ContactPointPhone",
"fieldName": "E164FormattedPhoneNumber",
"isRequired": true,
"applyHash": true,
"isIdentifier": true
},
{
"displayName": "Hashed Digital id value",
"destinationName": "DigitalIdValue",
"objectName": "ContactPointDigitalId",
"fieldName": "DigitalIdValue",
"isRequired": true,
"applyHash": true,
"isIdentifier": true
}
],
"fields": [
{
"name": "AccountId",
"helpText": "",
"isRequired": true,
"isHidden": false,
"type": "Text"
},
{
"name": "AccountName",
"helpText": "",
"isRequired": false,
"isHidden": true,
"type": "Text",
"values": [
{
"isDefault": true,
"value": "Name of your account"
}
]
}
],
"activationPlatformCustomMetadata": {
"connectorType": "S3",
"accessKey": "DUMMY1234EXAMPLE5678KEY",
"secretKey": "dUmMySeCrEtKeY12345EXAMPLE67890"
},
"activationPlatformAdditionalMetadata": {
"hashMethod": "SHA256",
"outputProperties": {
"outputFormat": "CSV",
"compression": "GZIP",
"maxFileSizeInMB": 128,
"maxRecordsPerFile": 1000000,
"minRecordsPerFile": 10000,
"outputPartitions": 20,
"delimiter": "COMMA"
},
"partnerSupportedIds": [
{
"destinationName": "DigitalIdValue",
"supportedIdTypes": [
"Google",
"Facebook",
"Trade desk",
"Instagram"
]
}
],
"subscriberOverrideOptions": {},
"supportCustomAttributes": false
}
}
Sample JSON for Output Grouping by PER_SEGMENT
{
"name": "abc-segment",
"apiName": "abc_segment",
"description": "ActivationTest platform to activate user identifiers and additional match keys",
"platformType": "Advertising",
"outputGrouping": "PER_SEGMENT",
"refreshMode": "FULL",
"connector": {
"connectorType": "S3",
"bucketName": "example-uswest2-cdp001-sample-data",
"exportDirectory": "datacloud-activations"
},
"activationAttributes": [
{
"displayName": "First Name",
"destinationName": "fName",
"objectName": "Individual",
"fieldName": "FirstName",
"isRequired": true,
"applyHash": false,
"isIdentifier": false
},
{
"displayName": "Last Name",
"destinationName": "lname",
"objectName": "Individual",
"fieldName": "LastName",
"isRequired": false,
"applyHash": false,
"isIdentifier": false
},
{
"displayName": "Hashed Digital id value",
"destinationName": "DigitalIdValue",
"objectName": "ContactPointDigitalId",
"fieldName": "DigitalIdValue",
"isRequired": true,
"applyHash": true,
"isIdentifier": true
},
{
"displayName": "Hashed Email",
"destinationName": "EmailAddress",
"objectName": "ContactPointEmail",
"fieldName": "Email",
"isRequired": false,
"applyHash": true,
"isIdentifier": true
}
],
"fields": [
{
"name": "AccountId",
"helpText": "",
"isRequired": true,
"isHidden": false,
"type": "Text"
},
{
"name": "AccountName",
"helpText": "",
"isRequired": false,
"isHidden": false,
"type": "Text"
}
],
"activationPlatformCustomMetadata": {
"connectorType": "S3",
"accessKey": "DUMMY1234EXAMPLE5678KEY",
"secretKey": "dUmMySeCrEtKeY12345EXAMPLE67890"
},
"activationPlatformAdditionalMetadata": {
"hashMethod": "SHA256",
"outputProperties": {
"outputFormat": "CSV",
"compression": "GZIP",
"maxFileSizeInMB": 128,
"maxRecordsPerFile": 1000000,
"minRecordsPerFile": 10000,
"outputPartitions": 20,
"delimiter": "COMMA"
},
"partnerSupportedIds": [
{
"destinationName": "DigitalIdValue",
"supportedIdTypes": [
"Google",
"Facebook",
"Trade desk",
"Instagram"
]
}
],
"subscriberOverrideOptions": {},
"supportCustomAttributes": false
}
}
| Field Name | Description | Required (Y/N) | Allowed Values | Sub Fields | Allowed Values | Sub Fields Description | Required (Y/N) |
|---|---|---|---|---|---|---|---|
| name | Name of the activation platform | Y | NA | NA | NA | NA | NA |
| apiName | Unique API name of the activation platform | Y | NA | NA | NA | NA | NA |
| description | A short description of the activation platform | Y | NA | NA | NA | NA | NA |
| platformType | Specifies the type of activation platform | Y | Advertising Publishing Analytics Marketing Technology |
NA | NA | NA | NA |
| logoUrl | The URL of the Activation Platform logo | N | NA | NA | NA | NA | NA |
| outputGrouping | Specifies how the activation payload output is delivered to the partner. Output grouping by segment groups all attributes within a segment into a single file, while output grouping by user identifier activates each user identifier in a separate file, such as CSV. This field can't be modified during the edit workflow. | Y | PER_SEGMENT PER_USER |
NA | NA | NA | NA |
| refreshMode | Refresh mode for the activation platform. For "outputGrouping":
"PER_USER" only Full is supported. |
Y | INCREMENTAL FULL |
NA | NA | NA | NA |
| refreshFrequency | Refresh frequency for the activation platform. Applicable only when
"outputGrouping": "PER_USER" is true |
Y | TWENTY_FOUR | NA | NA | NA | NA |
| periodicFullRefresh | Indicates how often you want to schedule a full refresh for Incremental
Refresh. Applicable only when "outputGrouping": "PER_SEGMENT" is
true and refresh mode is incremental. |
Y | REFRESH_30 REFRESH_60 |
NA | NA | NA | NA |
| connector | Amazon S3 Connector details | Y | NA | "connectorType" "bucketName" "exportDirectory" |
NA | exportDirectory: The folder path where the data is exported. | Y |
| activationPlatformCustom Metadata | Contains the connector credential details. | Y | NA | "connectorType" "accessKey" "accessSecret" |
NA | NA | Y |
| fields | An array containing details of the activation target fields. Add at least one field (for example, Account ID). You can add a maximum of five fields. | Y | NA | "name" | NA | The name of the field to be displayed in the activation target. | Y |
| NA | "helpText" | NA | A short descriptive text providing guidance for the field in the activation target. | N | |||
| NA | "isRequired" | true false |
Indicates whether the field is required. A required field can't be hidden, and vice versa. | Y | |||
| NA | "isHidden" | true false |
A required field can't be hidden, and vice versa. Hidden fields must always have a default value. | Y | |||
| NA | "type" | NA | The data type defined by the user based on the field requirement. | N | |||
| NA | "values" "isDefault" "value" |
NA | This is optional unless "isHidden": true, in which case, you
must set "isDefault": true and provide a default value as shown in
the example. Hidden fields must always have a default value. |
N | |||
| activationAttributes | The attributes array contains all attributes that you allow your customers to map, including details on required and optional attributes. After defining an attribute, it can’t be removed during edit flow. | Y | NA | "objectName" | NA | This is used as a hint for customers and it refers to the data model object
(DMO) name . This helps customers map destination fields to Data 360 DMO
attributes during activation mapping. For the ContactPointDigitalId
DMO, the object name must be "ContactPointDigitalId". |
N (Read further for specific conditions where this field is required.) |
| NA | "fieldName" | NA | This is used as a hint for customers and it refers to the attribute name in the DMO for the corresponding destination field. This helps customers map destination fields to Data 360 DMO attributes during the activation mapping process. |
N | |||
| NA | "displayName" | NA | The user-friendly name for the corresponding destinationName, which is displayed on the right side of the activation mapping interface. | Y | |||
| NA | "destinationName" | NA | Refers to the destination schema field name. This
destinationName is used as the column header in the exported
file (for example, CSV) when the output is grouped by segment. When the output is
grouped by a user identifier, destinationName is used as the
name of the folder that’s created automatically for each user identifier. This field
can’t be Id, ID, or id for any of the activation attributes. This field value is
displayed as thePreferred Attribute Namein the Contact Point
filtering page. |
Y | |||
| NA | "isRequired" | true false |
Indicates whether this attribute is a required field. | Y | |||
| NA | "isIdentifier" | true false |
Indicates whether this attribute is used as a user identifier. | Y | |||
| NA | "applyHash" |
true false |
Indicates whether the attribute value should be hashed during Activation. It is recommended to set this flag to "true" for user identifier fields, unless partners prefer to retain the original values without hashing. | Y | |||
| activationPlatformAdditional Metadata | This object contains additional metadata that partners can configure as needed. | NA | NA | "hashMethod" | "SHA256" | NA | Required if any field is set to "applyHash": true |
| NA | “outputProperties" "outputFormat" |
CSV JSON PARQUET |
NA | Y | |||
| NA | "compression" | GZIP BZIP2 NONE |
NA | Y | |||
| NA | "maxFileSizeInMB" | Defaults to 128 MB if not configured | Make sure that no file exceeds the specified file size. Recommended to not exceed 512 MB. | N | |||
| NA | "maxRecordsPerFile" | Defaults to 1 million records per file if not configured | Make sure that no file contains more than the specified number of records. Recommended to not exceed 5 million. | N | |||
| NA | "minRecordsPerFile" | Min -1 | The minimum number of records that must be present in a file. | N | |||
| NA | "outputPartitions” | Min -1 | Controls the number of files created in the output payload. | N | |||
| NA | "delimiter” | COMMA SEMICOLON TAB PIPE COLON TILDE CARET HASH UNDERSCORE BROKEN_PIPE SLASH |
NA | Required if the output format is CSV | |||
| NA | "partnerSupportedIds" | NA | NA | Required if ContactPointDigitalId is used as objectName in activationAttributes | |||
| NA | "destinationName" | NA | The field name on the destination schema which accepts Digital identifiers. Once defined, this can’t be changed during edit flow. | ||||
| NA | "supportedIdTypes" | NA | The digital identifier types supported by the partner (for example, Google, Meta, Instagram). | Required if ContactPointDigitalId is used as objectName in activationAttributes |
Guidelines to Prevent JSON Validation Errors
- The apiName value can't contain spaces.
- When outputGrouping is set to
PER_USER, make sure that all the activation attributes are configured as identifiers by setting isIdentifier to true. - When outputGrouping is set to
PER_SEGMENT, make sure that at least one attribute is an identifier by setting isIdentifier to true. - Specify the hash method as "hashMethod": "SHA256" in activationPlatformAdditionalMetadata when atleast one attribute is set to “applyHash” : true.
- The array of fields in the activation target must contain at least one entry, but can’t exceed five entries. AccountId is a required field. Use the field "name": "AccountId" as provided in the sample JSON. Don’t update or remove this field.
- If you’re including ContactPointDigitalId as objectName in the attributes list, provide the "PartnerSupportedIds" object in the activationPlatformAdditionalMetadata. Make sure that the destinationName for ContactPointDigitalId matches the destinationName specified in “partnerSupportedIds.” Don’t use Id, ID, or id as the destinationName for any of the activation attributes.
- If the destinationName of an activationAttribute matches the destinationName of partnerSupportedIds, specify the objectName for such an activationAttribute as "objectName": "ContactPointDigitalId".
- If partnerSupportedIds is defined, specify the supportedIdTypes, and don't enter null for the destinationName field.
- At least one supportedIdTypes must be retained when updating the JSON.
Important After creating the package and setting up the
activation platform, don't update the JSON to change
outputGrouping,
destinationName, or remove activation attributes or
supportedIdTypes. These changes could impact existing customers who have
already set up activations using these configurations.Best Practices and Recommendations
- For email data normalization to work, set the preferred destinationName for email to EmailAddress(case-sensitive).
- Set "applyHash" : true at each attribute level if you want to hash the user identifier values for attributes such as email and phone.
- After activation, certain folders are automatically created in the Amazon S3 bucket with the preferred destinationName. However, when the Contact Point Digital Id DMO is used, the values specified by the ISV partner in the supportedIdTypes field are used as folder names.
- For optimal performance, it's recommended not to exceed 512 MB for maxFileSizeInMB. If this optional field isn't configured, it defaults to 128 MB.
- It's recommended to not exceed 5,000,000 maxRecordsPerFile. If this optional field isn't configured, the system defaults to 1,000,000 records.
- Including maxFileSizeInMB and maxRecordsPerFile values make sure that each output file stays within the specified size and record count limits.
- Make sure that minRecordsPerFile is less than or equal to maxRecordsPerFile, if configured.
- The outputPartitions controls the number of files generated in the output location per activation job. When output is grouped by segment, the outputPartitions defined in the JSON is applied per segment publish, which is considered an activation job. See Find External Activation Platform Segments in Cloud File Storage for more information.
- When the platform output is grouped per user identifier, then the 24-hour refresh frequency is considered as an activation job for each activation target created by the customer. See Find External Activation Platform Segments in Cloud File Storage for more information.
- outputPartitions and minRecordsPerFile determine how data is divided into partitions. If outputPartitions is set, it takes precedence. Otherwise, partitions are calculated based on minRecordsPerFile and the total number of records in all the output files. If the outputPartitions field isn't configured, the total record count is divided by minRecordsPerFile value to calculate the number of partitions.
- In the PartnerSupportedIds section, include under supportedIdTypes only those attributes that are mapped to ContactPointDigitalId in the activationAttributes section. For example, exclude email and phone attributes from supportedIdTypes if they aren’t mapped to ContactPointDigitalId.
Did this article solve your issue?
Let us know so we can improve!
