JSON Metadata Usage and Examples for External Activation Platforms

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
}
}

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 run. When output is grouped by segment, the outputPartitions defined in the JSON is applied per segment publish, which is considered ‌an activation run. 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 run 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.

Note When the exportDirectory is set to "exportDirectory": "/", activation files are uploaded to the root directory of the specified S3 bucket. A date-based folder structure is automatically created and maintained to organize the exported files.