An Outline of Types

Outlining types of data returned from the NativeX API

Introduction

In order to best outline the returned results of a given query this will outline the shape of various data types returned via the API as well as cover the Connection approach to returning data via GraphQL.

What is a connection?

Return types ending in Connection will return data in a format akin to the following:

{
  "data": {
    "totalCount": A_NUMBER,
    "edges": [
      {
        "node": {
        Various Returned Data For Type "Connected To" Goes Here...
        }
      }...
    ],  
    "pageInfo": {
      "hasNextPage": true/false,
      "endCursor": CURSOR_STRING_VALUE    
  },
}

This means for a given Connection, provided the same query with "next" cursors for their respective connection this will allow for pagination of a given "fragment" of data for the query. This is important to be able to query for say all Campaigns from the same Advertiser or all Creatives for a given Campaign as necessary.

Note: Most of these connections default to return the first 25 most recently created items for their given connection, for how this can be adjusted take a look at the Queries section.

Type Overview

Next we'll take a look at various data types and their respective shapes to outline what is being returned and where.

Advertiser

Advertisers can have Campaigns (and by extension Creatives) and Stories. Here is the information that can be returned for an Advertiser:

id - The ID for the Advertiser (used for queries that require an Advertiser ID)
hash - The hash for the Advertiser (used for queries that require an Advertiser Hash)
name - The name of the Advertiser
logo - Includes id, src, filename, size, width and height subfields
website - The advertiser's website
externalId - An external ID for the advertiser should one be available
deleted - Whether or not the Advertiser has been marked as deleted
createdAt - A UNIX timestamp when the Advertiser was added to NativeX
updatedAt - A UNIX timestamp when the Advertiser was last updated in NativeX
campaigns - A list of campaigns for the given Advertiser using the CampaignConnection type, see Campaign for more detail as to what is returned regarding campaigns
stories - A list of stories for the given Advertiser using the StoryConnection type, see Story for more detail as to what is returned regarding stories.

Campaign

Campaigns contain information regarding where and how advertising items are suppose to appear on site and within e-mail as well as various metrics regarding performance. Here is the information that can be returned for a Campaign:

id - The ID for the Campaign (used for queries that require a Campaign ID)
hash - The hash for the Campaign (used for queries that require a Campaign Hash)
name - The name of the Campaign
description - A description for the Campaign
createdAt - A UNIX timestamp for when the Campaign was created within NativeX
updatedAt - A UNIX timestamp for when the Campaign was updated within NativeX
advertiser - The Advertiser for the associated Campaign. See Advertiser for more detail as to what is returned regarding advertisers.
story - The Story for the associated Campaign. See Story for more detail as to what is returned regarding stories.
status - Returns one of the following Deleted, Incomplete, Finished, Paused, Running, Scheduled
requires - Returns a string noting what the Campaign still needs before it is able to run
deleted - Whether or not the campaign has been deleted
paused - Whether or not the campaign has been paused
requiredCreatives - Returns the number of creatives required by the Campaign
publishers - A list of publishers for the given campaign using the PublisherConnection type, see Publisher for more detail as to what is returned regarding publishers.
emailLineItems - A list of email line items for the given campaign using the EmailLineItemConnection type, see Email Line Item for more detail as to what is returned regarding email line items.
url - The URL that is linked to for items in the campaign.
primaryImage - Includes id, src, filename, size, width and height subfields (this typically returns the image associated with the first creative for a campaign) (Needs clarification)
creatives - A list of creatives for the given campaign see Campaign Creative for more detail as to what is returned regarding creatives.
criteria - Includes subfields of start and end (UNIX timestamps for start and end of Campaign) as well as a list of placements (as the placements subfield), see Placement for more detail as to what is returned regarding placements.
externalLinks - A list of external links including the label as well as url on each link.
metrics - Includes subfields of views, clicks and ctr (all numbers) regarding Campaign performance.
reports - Includes a byDay subfield which requires input of startDate and endDate (both of which are UNIX timestamps) which then includes an additional subfields of day which requires input of format ("MMMM Do YYYY" should work and will provide a date in the format August 5th 1999) and metrics which returns the same information as the Campaign metrics field albeit for the individual day of the Campaign instead of the entire Campaign.

Campaign Creative

id - The id for the Campaign Creative (used for queries that require a Campaign Creative ID)
title - The title for the Campaign Creative
teaser - The teaser for the Campaign Creative
linkText - The text that appears for the link associated with the Campaign Creative (ex: Click here to download!)
active - Whether or not the Campaign Creative is active
image - Includes id, src, filename, size, width and height subfields
metrics - See Campaign.metrics for fields and data provided, this applies to the returned creative(s) as appropriate
reports - See Campaign.reports for fields and data provided, this applies to the returned creative(s) as appropriate

Placement

id - The id for the Placement (used for queries that require a Placement ID)
name - The name of the placement
publisher - The publisher associated with the placement see Publisher for more detail as to what is returned regarding publishers.
topic - The topic associated with the placement includes subfields for id, name, publisher, placements and externalId
reservePct - The percentage of impressions that are reserved for content, rather than ads.
createdAt - A UNIX timestamp for when the Placement was created within NativeX
updatedAt - A UNIX timestamp for when the Placement was updated within NativeX
metrics - Contains the same fields as Campaign.metrics but additionally requires input of start and end as UNIX timestamps in order to determine the window to examine metrics for

Publisher

Publishers end up being the root of NativeX as publishers contain the placement information for NativeX advertisements for both email and website products. Here is the information that can be returned for a Publisher:

id - The id for the Publisher (used for queries that require a Publisher ID)
name - The name of the Publisher
domainName - If configured the custom domain to serve NativeX Story content on
storyPath - If configured the custom path on the publisher website to serve NativeX story content on
website - The publisher website
logo See Advertiser.logo
topics See Placement.topic the difference here is this is done via the TopicConnection type
placements A list of placements for the publisher on their respective website using the PlacementConnection type, see Placement for more detail regarding what is returned regarding placements
campaigns - A list of campaigns for the publisher on their respective website using the CampaignConnection type, see Campaign for more detail regarding what is returned regarding campaigns
emailDeployments - A list of email deployments for the publisher on their respective products using the EmailDeploymentConnection type, see Email Deployment for more detail regarding what is returned regarding email deployments
emailPlacements - A list of email placements for the publisher on their respective products using the EmailPlacementsConnection type, see Email Placement for more detail regarding what is returned regarding email placements
createdAt - A UNIX timestamp for when the Publisher was created within NativeX
updatedAt - A UNIX timestamp for when the Publisher was updated within NativeX
metrics - See Placement.metrics except this applies for the publisher as a whole over individual placements

Story

NativeX Stories operate as a full page extension of the NativeX advertising platform allowing for additional engagement opportunities. Here is the information that be returned for a Story:

id - The id for the Story (used for queries that require a Story ID)
hash - The hash for the Story (used for queries that require a Story Hash)
title - The title of the Story
slug - A human readable identifier for the story that is a part of the stories website path
advertiser - The advertiser associated with the Story, see Advertiser for more detail regarding what is returned regarding advertisers.
publisher - The publisher associated with the Story, see Publisher for more detail regarding what is returned regarding publishers.
teaser - The teaser for the Story
body - The body copy of the Story
path - The path to the Story on the website it displays on
status - Options are Deleted, Placeholder, Published, Scheduled or Draft
placeholder - Whether or not the Story is a placeholder
deleted - Whether or not the story is deleted
publishedAt - A UNIX timestamp for when the Story was published
primaryImage - Includes id, src, filename, size, width and height subfields
images - A list of images including the same information as primaryImage
previewUrl - The URL the story can be previewed on, helpful for when a Story is not yet published
url - The URL the story can be viewed on when published
campaigns - A list of campaigns for the given Story using the CampaignConnection type, see Campaign for more detail as to what is returned regarding campaigns
createdAt - A UNIX timestamp for when the Story was created within NativeX
updatedAt - A UNIX timestamp for when the Story was updated within NativeX
metrics - Includes pageviews, uniquePageviews, sessions, users, avgSessionDuration, bounceRate, timeOnPage, avgTimeOnPage and shares subfields all of which are numbers of some kind (integer or decimal)
reports - Includes: AbyDay subfield which requires input of startDate and endDate (both of which are UNIX timestamps) which then includes an additional subfields of day which requires input of format ("MM-DD-YYYY" should work (CONFIRM THIS)) and metrics which returns the same information as the Story metrics field albeit for the individual day of the Story's run instead of the entire Story's run. An acquisition subfield containing a list of publication channels (channelGrouping) and their respective metrics (metrics) using the same format as the Story metrics field albeit for the individual channel the Story ran in. Lastly this includes a devices subfield containing a list of the deviceCategory and metrics much like the other metrics but for a given device category.

Email Specific Type Overview

As NativeX allows for advertising on both email and website products there are some additional return types that are exclusive to email.

Email Deployment

id - The Email Deployment ID (used for queries that require an Email Deployment ID)
name - The name of the Email Deployment
fullName - The full name of the Email Deployment (typically includes some sort of prefix or suffix relative to the name field)
publisher - The publisher of the Email Deployment, see Publisher for more detail regarding what is returned regarding publishers.
placements - See Publisher.emailPlacements albeit this is limited to placements for the returned deployment
createdAt - A UNIX timestamp for when the Email Deployment was created within NativeX
updatedAt - A UNIX timestamp for when the Email Deployment was updated within NativeX

Email Line Item

id - The Email Line Item ID (used for queries that require an Email Line Item ID)
name - The name of the Email Line Item
campaign - The campaign the Email Line Item is a part of, see Campaign for more detail regarding what is returned regarding campaigns
placement - The placement the Email Line Item is placed at, see Email Placement for more detail regarding what is returned regarding email placements
dates - Includes start, end and days subfields, the first two of which are UNIX timestamps and the last of which is a list of UNIX timestamps that indicate the days by which the line item ran
status - See Campaign.status for values
requires - See Campaign.requires this operates similarly but for Email Line Items
paused - Whether or not the Email Line Item is paused
ready - Whether or not the Email Line Item is ready to be served
deleted - Whether or not the Email Line Item is deleted
createdAt - A UNIX timestamp for when the Email Line Item was created within NativeX
updatedAt - A UNIX timestamp for when the Email Line Item was updated within NativeX

Email Placement

id - The Email Placement ID (used for queries that require an Email Placement ID)
name - The name of the Email Placement
fullName - The full name of the Email Placement (usually including some sort of prefix or suffix relative to name)
emailDeployment - The email deployment the Email Placement is associated with, see Email Deployment for more detail regarding what is returned regarding email deployments
createdAt - A UNIX timestamp for when the Email Placement was created within NativeX
updatedAt - A UNIX timestamp for when the Email Placement was updated within NativeX

PreviousIntroduction NextAn Outline of Inputs

Last updated 2 years ago