Introduction to Campaigns
Gain a basic overview of CoreMedia Campaigns.
Welcome to the CoreMedia Campaigns documentation. In this introduction, you will get a basic overview of the campaign logic and how to request campaign data using GraphQL.
Prerequisites
In order to use CoreMedia Campaigns, you must meet the following requirements:
-
CMCC v.11.2210.1 and higher
-
CMCC-Service customer
-
Using the Headless Server for content delivery
Description of a Campaign
A campaign is a way to schedule content from CoreMedia Content Cloud to be visible on different, predefined slots on your website for a specific event.
Like advertising slots in the public (for example, main station entrance east 1st large billboard) or website ads, there are named slots available on your website. For example, a "Hero" slot exists for all pages. Campaign content can be shown in these slots. It is, for instance, also possible to create a campaign for a "summer-collection of dresses" only to be shown on category pages below "apparel > woman".
You create a campaign, using the Campaigns user interface, available from CoreMedia Studio. Here you specify which content from CoreMedia Content Cloud should appear in which slot and on what pages of your website.
Visibility of Campaigns
Date
To make campaigns run only for specific events, they are scheduled to be active between a start and end date/time. You will plan the active duration for each campaign and CoreMedia Campaigns Delivery API will automatically determine which campaign is currently active at each point in time.
Priority
If multiple campaigns run in parallel, a prioritization value on each campaign helps to define an order between those campaigns. For example, a general campaign "10% discount for Newsletter signup" should be shown everywhere on the website in the "hero" slot. It has a default priority of 5. If the before mentioned "summer collection of dresses" campaign ha a priority of 7, it will be shown instead of the medium prioritized "10% discount for Newsletter signup" campaign. Of course, you can also decide that you want to display both, for example, in a carousel. In this case, the prioritization is simply used to define the order of content items in a specific slot.
Characteristics of Campaign Content
Relation to a page
It is necessary to define on which page types your campaign content should be shown. For instance, you can choose a category page. By adding refinements to the page type, you can also narrow down the assignment to only specific subpages. For example, only on category page "woman".
Relation to a slot
In addition to the page, you have to define in what specific slot the content should be shown. When you have defined to show content for a category page, you can now define to shown in the hero slot of these pages.
Content
Lastly, you choose the content for the slot.
What is CoreMedia Campaigns?
With the CoreMedia Campaigns Delivery API the frontend developer gets one endpoint to retrieve content IDs that are managed via the Campaign App for the queried site-id, channel types and refinements. These IDs then can be used to request more detailed information about single content from the Headless Server.
Features
Campaigns offers a great interface to request campaign data from. You can either use the builtin GrapiQl or the ApolloGraphQL interfaces.
Restriction by channel type
Campaigns can be defined for different types of pages (for instance: category pages, cms pages and the like). These different types are called "channel type".
Refinements
In the window of the channel type "Category Page" you can see possible filtering words divided by comma. These filters are called refinements in this context.
Example campaign with defined refinements
Assignment
The "assignment" is the relation between the following parts: * A Content is * defined for a slot * inside a page * connected to a campaign * plus additional information provided by refinements
To give an example-assignment seen in the picture above:
The content Things you can do wrong with your evening Dresses, defined for the hero slot, inside the category page, connected to the campaign summer-collection-t-shirts and specified by refinements summer and clothing.
Getting the Content with GraphQL
As CoreMedia Campaigns is a headless service, it offers a Delivery API based on GraphQL. This API can be used by your website frontend to request the currently active campaign content for a specific page and slot. All campaigns that are currently actively running and that define content for a page and furthermore slot can be returned.
Only the summer collection Campaigns are retrieved for the site with the id "ced8921…"
To get the desired content managed via campaigns, for instance, all campaigns that should be visible on category pages and are visible for the summer, a query like shown in the picture above would be correct.
How do I get a specific campaign?
You don’t. The Campaigns Delivery API is not designed to retrieve specific campaigns by name or ID. It is rather the other way around. You perform a request where you specify the site and page you are working on and refinements relevant to that page ("women", for instance) and the API will return the appropriate content from all active campaigns.
What is the content of a campaign?
The content is divided by the channel types it references to, and after that, a campaign contains linked articles for slots, for example "Hero-slot".
Which campaign is returned if two with the same refinements exist?
The campaign with the highest priority will be returned if no exact match via refinements can be found. You can also request more than one results via the API, then you get them sorted by priority.
Overview of the Architecture
Campaign Delivery
Let’s assume a category landing page (clothing > dresses) is rendered. The client requests the Campaigns Delivery API with the channel type "category-page" and the refinements "clothing" and "dresses". The only campaign that defines content for this page is the "summer-collection dresses" campaign, because it is valid for every category page with refinement summer or clothing. The Delivery API will return the content UUIDs of the CoreMedia content that was assigned to the "hero" slot in the Campaign App for the Campaign "summer-collection dresses". Of course this only happens within the configured start and end date for the campaign and only if the campaign was set active.