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