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:
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 Advertiserlogo
- Includesid
,src
,filename
,size
,width
andheight
subfieldswebsite
- The advertiser's websiteexternalId
- An external ID for the advertiser should one be availabledeleted
- Whether or not the Advertiser has been marked as deletedcreatedAt
- A UNIX timestamp when the Advertiser was added to NativeXupdatedAt
- A UNIX timestamp when the Advertiser was last updated in NativeXcampaigns
- A list of campaigns for the given Advertiser using theCampaignConnection
type, see Campaign for more detail as to what is returned regarding campaignsstories
- A list of stories for the given Advertiser using theStoryConnection
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 Campaigndescription
- A description for the CampaigncreatedAt
- A UNIX timestamp for when the Campaign was created within NativeXupdatedAt
- A UNIX timestamp for when the Campaign was updated within NativeXadvertiser
- 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 followingDeleted, Incomplete, Finished, Paused, Running, Scheduled
requires
- Returns a string noting what the Campaign still needs before it is able to rundeleted
- Whether or not the campaign has been deletedpaused
- Whether or not the campaign has been pausedrequiredCreatives
- Returns the number of creatives required by the Campaignpublishers
- A list of publishers for the given campaign using thePublisherConnection
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 theEmailLineItemConnection
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
- Includesid
,src
,filename
,size
,width
andheight
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 ofstart
andend
(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 ofviews
,clicks
andctr
(all numbers) regarding Campaign performance.reports
- Includes abyDay
subfield which requires input ofstartDate
andendDate
(both of which are UNIX timestamps) which then includes an additional subfields ofday
which requires input offormat
("MMMM Do YYYY" should work and will provide a date in the format August 5th 1999) andmetrics
which returns the same information as the Campaignmetrics
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 Creativeteaser
- The teaser for the Campaign CreativelinkText
- 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 activeimage
- Includesid
,src
,filename
,size
,width
andheight
subfieldsmetrics
- SeeCampaign.metrics
for fields and data provided, this applies to the returned creative(s) as appropriatereports
- SeeCampaign.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 placementpublisher
- 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 forid
,name
,publisher
,placements
andexternalId
reservePct
- The percentage of impressions that are reserved for content, rather than ads.createdAt
- A UNIX timestamp for when the Placement was created within NativeXupdatedAt
- A UNIX timestamp for when the Placement was updated within NativeXmetrics
- Contains the same fields asCampaign.metrics
but additionally requires input ofstart
andend
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 PublisherdomainName
- If configured the custom domain to serve NativeX Story content onstoryPath
- If configured the custom path on the publisher website to serve NativeX story content onwebsite
- The publisher websitelogo
SeeAdvertiser.logo
topics
SeePlacement.topic
the difference here is this is done via theTopicConnection
typeplacements
A list of placements for the publisher on their respective website using thePlacementConnection
type, see Placement for more detail regarding what is returned regarding placementscampaigns
- A list of campaigns for the publisher on their respective website using theCampaignConnection
type, see Campaign for more detail regarding what is returned regarding campaignsemailDeployments
- A list of email deployments for the publisher on their respective products using theEmailDeploymentConnection
type, see Email Deployment for more detail regarding what is returned regarding email deploymentsemailPlacements
- A list of email placements for the publisher on their respective products using theEmailPlacementsConnection
type, see Email Placement for more detail regarding what is returned regarding email placementscreatedAt
- A UNIX timestamp for when the Publisher was created within NativeXupdatedAt
- A UNIX timestamp for when the Publisher was updated within NativeXmetrics
- SeePlacement.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 Storyslug
- A human readable identifier for the story that is a part of the stories website pathadvertiser
- 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 Storybody
- The body copy of the Storypath
- The path to the Story on the website it displays onstatus
- Options areDeleted
,Placeholder
,Published
,Scheduled
orDraft
placeholder
- Whether or not the Story is a placeholderdeleted
- Whether or not the story is deletedpublishedAt
- A UNIX timestamp for when the Story was publishedprimaryImage
- Includes id, src, filename, size, width and height subfieldsimages
- A list of images including the same information asprimaryImage
previewUrl
- The URL the story can be previewed on, helpful for when a Story is not yet publishedurl
- The URL the story can be viewed on when publishedcampaigns
- A list of campaigns for the given Story using theCampaignConnection
type, see Campaign for more detail as to what is returned regarding campaignscreatedAt
- A UNIX timestamp for when the Story was created within NativeXupdatedAt
- A UNIX timestamp for when the Story was updated within NativeXmetrics
- Includespageviews
,uniquePageviews
,sessions
,users
,avgSessionDuration
,bounceRate
,timeOnPage
,avgTimeOnPage
andshares
subfields all of which are numbers of some kind (integer or decimal)reports
- Includes: AbyDay
subfield which requires input ofstartDate
andendDate
(both of which are UNIX timestamps) which then includes an additional subfields ofday
which requires input offormat
("MM-DD-YYYY" should work (CONFIRM THIS)) andmetrics
which returns the same information as the Storymetrics
field albeit for the individual day of the Story's run instead of the entire Story's run. Anacquisition
subfield containing a list of publication channels (channelGrouping
) and their respective metrics (metrics)
using the same format as the Storymetrics
field albeit for the individual channel the Story ran in. Lastly this includes adevices
subfield containing a list of thedeviceCategory
andmetrics
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 DeploymentfullName
- 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
- SeePublisher.emailPlacements
albeit this is limited to placements for the returned deploymentcreatedAt
- A UNIX timestamp for when the Email Deployment was created within NativeXupdatedAt
- 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 Itemcampaign
- The campaign the Email Line Item is a part of, see Campaign for more detail regarding what is returned regarding campaignsplacement
- The placement the Email Line Item is placed at, see Email Placement for more detail regarding what is returned regarding email placementsdates
- Includesstart
,end
anddays
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 ranstatus
- SeeCampaign.status
for valuesrequires
- SeeCampaign.requires
this operates similarly but for Email Line Itemspaused
- Whether or not the Email Line Item is pausedready
- Whether or not the Email Line Item is ready to be serveddeleted
- Whether or not the Email Line Item is deletedcreatedAt
- A UNIX timestamp for when the Email Line Item was created within NativeXupdatedAt
- 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 PlacementfullName
- 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 deploymentscreatedAt
- A UNIX timestamp for when the Email Placement was created within NativeXupdatedAt
- A UNIX timestamp for when the Email Placement was updated within NativeX
Last updated