Delivery GraphQL API

Last updated a month ago

Describes the Campaign Delivery API.

Table of Contents

Prerequisites
Basic API Information
- Campaign Delivery API Authentication
- Campaign Preview API Authentication
GraphQL API

Prerequisites

A CoreMedia Content Cloud account
A valid Token to access the Campaign Delivery Service

Basic API Information

Base URL: https://api.campaigns.coremedia.io

Campaign Delivery API Authentication

The Campaign Service GraphQL Delivery API needs authentication via an Authorization HTTP header. You receive the token together with your login information. In the following, we will call this token delivery access token.

Campaign Preview API Authentication

In addition to the delivery access token you also get a preview access token in order to use the Campaign Preview API. Using the preview token you can access all delivery and preview related queries and fields. The preview token also needs to be provided via 'Authorization' HTTP Header.

GraphQL API

Besides the following API documentation, you can access the interactive schema based API documentation below the API Base URL.

Query.campaignContent

This query retrieves slot definitions and the associated contents managed in the Campaign App. This query only takes running campaigns into account.

SlotResult exposes an array of Slot objects while the Slot objects provide a name, a (primary) assignment, and the list of assignments. The resulting slot assignment comes from the campaign that has the highest priority among matching running campaigns. Slot assignments with lower priority are available below path 'Query.campaignContent.slots.assignments'.

Each Assignment object contains list of content items, which only hold the UUID of the referenced CoreMedia content. The content UUID then needs to be resolved/transformed to the real content data externally via Schema Stitching, Apollo Federation or equivalent solutions.

campaignContent(site: String!, channelType: String!, refinements: [String!]): SlotResult!

Query Parameters

Name

Description

Required

Default

Examples

site

the site id

yes

"ced8921aa7b7f9b736b90e19afc2dd2a" (site id calista en-us)

channelType

Key used for the template type. Available values can be queried via "channelTypes".

"category-page", "content-page", "product-page"

refinements

Sorted list of refinements. Only one of the requested refinements must match one of the refinements defined in the campaign data to be part of the result. The most important refinement should be defined first in the array, in case of multiple search hits.

for a category-page: "women-dresses"

for a content-page: "82be5043-e2d8-4db4-a6cb-3b58c2213825" (the UUID of a CoreMedia Content)

Details

Example Query:

query CampaignContent(
  $site: String!
  $channelType: String!
  $refinements: [String!]
  $names: [String!]
  $limit: Int
) {
  campaignContent(
    site: $site
    channelType: $channelType
    refinements: $refinements
  ) {
    slots(names: $names) {
      name
      assignment {
        items {
          id
        }
      }
      assignments(limit: $limit) {
        refinements
        items {
          id
        }
      }
    }
  }
}

Query Variables:

{
  "site": "ced8921aa7b7f9b736b90e19afc2dd2a",
  "channelType": "category-page",
  "refinements": ["apparel", "women"],
  "limit": 5,
  "names": "main"
}

Response:

{
  "data": {
    "campaignContent": {
      "slots": [
        {
          "name": "main",
          "assignment": {
            "items": [
              {
                "id": "8d8ba1e8-183d-4c40-947c-b5fb8f0a1842"
              }
            ]
          },
          "assignments": [
            {
              "refinements": [],
              "items": [
                {
                  "id": "8d8ba1e8-183d-4c40-947c-b5fb8f0a1842"
                }
              ]
            },
            {
              "refinements": [],
              "items": [
                {
                  "id": "92ba478a-71b1-47ee-89b6-308981bcdfe0"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Query.previewCampaign

Returns slots and the assignments managed in a campaign with a given campaign id. The campaign does not need to be in state running to be previewed.

The content of the returned 'SlotResult' has the same format as the one coming from 'Query.campaignContent'. It contains content managed in the campaign with the given campaign id.

You need to provide a valid preview access token as "Authorization" Header to use this query.

  previewCampaign(campaignId: ID!, channelType: String!, refinements: [String!]): SlotResult!

Query Parameters

Name

Description

Required

Default

Examples

campaignId

the campaign id

yes

"efa50df7-4906-4306-b7d3-e9a065a6144a"

channelType

Key used for the template type. Available values can be queried via "channelTypes".

"category-page", "content-page", "product-page"

refinements

for a category-page: "women-dresses"

for a content-page: "82be5043-e2d8-4db4-a6cb-3b58c2213825" (the UUID of a CoreMedia Content)

Details

Example Query:

query ( $campaignId: ID!, $channelType: String!, $names: [String!], $limit: Int, $refinements: [String!]) {
  previewCampaign( channelType: $channelType, campaignId: $campaignId, refinements: $refinements) {
    slots(names: $names) {
      id
      name
      assignment {
        items {
          id
        }
      }
    }
  }
}

Query Variables:

{
  "campaignId":"efa50df7-4906-4306-b7d3-e9a065a6144a",
  "channelType": "content-page",
  "refinements":["b3981d0b-7981-4289-85d7-565823679b18"],
  "names":["hero", "header"]
}

Response:

{
  "data": {
    "previewCampaign": {
      "slots": [
        {
          "name": "header",
          "assignment": {
            "items": [
              {
                "id": "8d8ba1e8-183d-4c40-947c-b5fb8f0a1842"
              }
            ]
          }
        },
        {
          "name": "hero",
          "assignment": {
            "items": []
          }
        }
      ]
    }
  }
}

Query.previewCampaignContent

Use previewCampaignContent to display campaign managed content, even if the campaign is still in status DRAFT or PAUSED. The parameters and the result type of previewCampaignContent are equivalent to Query.campaignContent with two additional and optional parameters previewDate and status.

The parameter previewDate sets a simulated date of view for the preview to see how the campaigns will look like in the future. The format of the string needs to be a valid ISO 8601 DateTime string. In other words, valid datetime strings of the form YYYY-MM-DDThh:mm:ss.SSSZ are accepted. The time zone offset is compulsory and must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss.

The parameter status contains a list of campaign status to be considered for preview. Allowed values are DRAFT (represents Draft, and Paused), and ACTIVE (represents Planned, and Running).

You need to provide a valid preview access token as Authorization Header in order to use this query.

  previewCampaignContent(site: String!, channelType: String!, refinements: [String!], previewDate: String, status: [CampaignStatus!]): SlotResult!

Query.channelTypes

Returns the list of channel types for a given site. A channel type is a mandatory parameter for Query.campaignContent.

channelTypes(site: String):[String!]

Query Parameters

Name

Description

Required

Default

Examples

site

the site id

"ced8921aa7b7f9b736b90e19afc2dd2a" (site id calista en-us)

Details

Example Query:

query Query {
  channelTypes
}

Response:

{
  "data": {
    "channelTypes": [
      "category-page",
      "content-page",
      "product-page",
      "transactional-page"
    ]
  }
}

Query._service

Expose the service description in case you want to use Apollo Federation. This query is called implicitly, when connected with an Apollo Federation Server. See https://www.apollographql.com/docs/federation/federation-spec

_service

Details

Example Query:

query Query {
  _service {
    sdl
  }
}

Is this page useful?