Introduction to Campaigns
Gain a basic overview of the campaign service.
Welcome to the CoreMedia Campaign Service documentation. In this introduction you will get a basic overview of the campaign logic and how to request campaign data using GraphQL.
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.
Similar to 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".
A campaign is created, using the Campaign App user interface, launchable from CoreMedia Studio. Here you are able to 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 the CoreMedia Campaign Service will automatically determine which campaign is currently active at each point in time.
Priority
In case 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 would have 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 is supposed to 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 it needs to be defined what specific slot the content is to be shown in. 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 the Campaign Service?
With the campaign delivery component 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
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 the CoreMedia Campaign Service is a headless service, it offers a Ddelivery 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 campaign service 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 service 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 Campaign 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 Service 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.