Gone are the days when copywriters must have access to physical products and do numerous online searches for inspiration to complete their copywriting tasks. With the Creative Force Copywriting Module, everything is brought to the copywriter be it Copywriting requirements, product images, and reference copy directly from the PIM!
This article will guide you through the latter to help you set up a Custom Content Widget that integrates with an API exposed by the customer to fetch and display text and images generically.
Need a brush up on the basics of Copywriting first? Click here for an Overview of Copywriting, and how to set up Copywriting Workflow and Copywriting style guides in Creative Force.
Please note, before moving on: Custom Content Widget is part of the Copywriting Module only and requires Text Production Types to be enabled in your workflow, and in the Copywriting Style Guide.
Go to Style Guide -> Copywriting. If you don’t have a Configuration yet for Copywriting, click ‘Create new’; if you already have an existing Configuration, click ‘Edit’.
Then, click ‘Add fields’ -> ‘Widget’ -> ‘Create Widget’. You can name it however you like but keep in mind that it should be less than 256 characters, the default is ‘External Content Viewer’. It is possible to add multiple instances of the External Content Viewer, up to 3 on the same layout.
After naming the widget, click ‘Continue’. You will then see the setup box appear.
API secret key:
You can use your existing key to fill in here. It is possible to use the same key across all the Widget instances.
The maximum length of API Secret Key is 256 characters
If you need a new key, click this icon to generate a new one.
The API Secret Key should be placed on the HTTP request header. Please refer to this document https://swagger.io/docs/specification/authentication/api-keys/
API URL:
Example URL could look like this: https://externaldomain.com/api/v1/existingContent
Only the GET Method is supported
The HTTP schema must be HTTPS for security reasons. We only support schema version 1.0.0
The length of the URL, including query parameters, must be less than 2048 characters
Query parameter:
These are Merge Fields allowing you to add Product Properties as parameter variables to build the request.
You can add up to 50 parameters and they must have values added.
Requirements for the API
The Custom Content Widget only supports JSON formatted responses with text content in the form of Markdown or plain text. You must follow the format below to get a successful response.
The response payload can contain 3 different types of objects in an array called “elements”:
“elementTitle” // a string rendered as a title inside the Widget at runtime.
“elementText” // provided in Markdown or plain text and rendered accordingly.
“elementImages” // an array of links to image files.
Important! In order for the Custom Display Widget to work, the below JSON schema must be followed in the API response.
{
"metadata": {
"requestId": "c02f0f73-4665-4aae-aac1-c2fbc65365de",
"schemaVersion": "1.0.0"
},
"data": {
"title": "Here you can put a title", //optional
"elements": [{
"elementTitle": "Element 1 Title", //optional
"elementText": [{
"format": "markdown", //plain_text | markdown,
"value": "# This is the text value of a text element."
}
],
"elementImages": [{
"imageUrl": "https://www.domain.com/image_1.jpg",
}, {
"imageUrl": "https://www.domain.com/image_2.jpg",
}, {
"imageUrl": "https://www.domain.com/image_3.jpg"
},
]
}, {
"elementTitle": "Element 2 Title", //optional
"elementText": [{
"format": "markdown", //plain_text | markdown,
"value": "And here's the text value of another text"
}
],
"elementImages": [{
"imageUrl": "https://www.domain.com/image_4.jpg",
},{
"imageUrl": "https://www.domain.com/image_5.jpg",
},{
"imageUrl": "https://www.domain.com/image_6.jpg",
},{
"imageUrl": "https://www.domain.com/image_7.jpg",
},{
"imageUrl": "https://www.domain.com/image_8.jpg",
},{
"imageUrl": "https://www.domain.com/image_9.jpg"
}
]
}
]
}
}
When the API is ready and the settings are filled in
After filling in the fields, you can click ‘Test’ to check the external integration. After clicking ‘Test’ you will see the Test Data Response box appear. Here, you will have two tabs Preview and Raw Response to check the results.
Preview tab: Showing the content rendered exactly as it will appear on the Task Page
Raw tab: Showing the response in the raw format (in JSON) from the API response.
Note: The request timeout to the external API is 20 seconds and the response size must be less than 1 MB
Presenting Content: If the request to the external API is successful, the response JSON will be parsed to the HTML of the widget and render the JSON “elements” in the following way.
All content in the JSON file will be presented generically in one single, scrollable view without adding any pagination or anything other than standard styling and positioning of the elements.
Images will be rendered as thumbnails which can be clicked to open a full screen preview. If an image is not possible for the widget to load, the image link will be shown providing the option to access the image via the web browser instead.
Once you are happy with the result, you can click ‘Save’ on the settings box to apply this to the copywriting tasks. When working on a copywriting task, the copywriter can then see the data generated from this widget.
Currently we support the following markdown elements:
Heading
Bold
Italic
Blockquotes
Lists (Order/Unorder)
Code block
Link