This page documents Amplified's internal data format for Advert Views: The Imperfect JSON.
The Imperfect JSON represents a single Advert View and all data associated with that AdView, including demographics, gaze, attentive seconds, channel context, brand name. All in one place, no more joins!
You can surf through this document to see what's availible by default in every ImperfectJSON.
But this Document is only a minimum specification, so pipeline projects may add extra properties at their own discretion.
Providing this value at the root of the schema informs code ediors of the structure of the file, enabling tooling like autocomplete and hover descriptions
"https://imperfect-json.amplifiedintelligence.io/imperfect-schema.json"
A unique identifier for this Advert View across all groups.
The list of Projects that were used to generate this Imperfect JSON. Projects should be listed in the order which they were applied.
A unique identifier for the repository that modified the file. Should follow the format amplifiedintelligence/[GIT_REPO_NAME]/[SUB_PROJECT]
"amplifiedintelligence/groups-monorepo/group-data-recovery"
"amplifiedintelligence/attention-pipeline"
"amplifiedintelligence/output-scripts"
A unique version string for the project, if your repository does not use semantic versioning, a short git commit hash should be used instead.
"4f2b2bc5"
"1.0.2"
A dictionary of metadata relating to the Respondent. Other fields than the keys below may be present.
The Collection Group Id this Respondent belongs to. All respondents within a group will usually complete the same set of tasks, with multiple groups per project to represent variations.
"K4DQ-2A"
"C9AU-25-1021-LINEARTV"
"C7AU-63-0122-CTV"
"REDC-64-0122-IRL-TWITTER-INFEEDVIDEO"
A unique Id for this Respondent within the context of the current GroupId. RespondentIds are usually an incrementing number.
"0"
"5"
"00005"
A unique Id for each AppSession a respondent launches within the context of the current RespondentId. assignmentIds are usually an incrementing number, but then can also include other text.
"0"
"1"
"2"
A respondent generated for testing within Amplified.
A respondent sourced from an external provider I.E. Cint
Panel Providers usually provide an identifier of their own for each Respondent.
Usually these are just UUIDs. So we need to associate these IDs with the Panel
they came from.
A unique identifier for the Panel Provider.
"cint"
"lucid"
"gapfish"
The Identifier issued to the Respondent by their external Panel Provider
"04b7ab87-6712-41e6-9cb7-2282969a809c"
"cf29ca1a-a7d3-406f-a25b-df053ffac079"
"9fb2e9c1-3f6b-47dd-a582-8d617b72a4f8"
A unique identifier for this person.
"27e109a45bebf5964de6d5d75814d24b31e0549d5fb1bbfb5fe296b45a046814"
Were the gender & ageRange fields inferred using Machine Learning? If false, assume values were provided through a demographic survey answered by the respondent
An ISO 3166 Alpha 2 country code, specifying which country this respondent lives in
"AU"
"UK"
"US"
"DE"
"ES"
The Respondents Gender, if provided
The respondent's age.
The respondent's ethnicity. (This field is a string as the survey answers are currently not standardised).
The respondent's postcode. (This field is a string as postcode formats differ by region).
Information about the Hardware and Software of the Device used to record this AdView.
The name of the App used to record this Advert View.
"attentionTRACE Research"
App Version String
"2.14.2"
Apple iOS specific information about the device.
iOS Version String
"13.1.2"
"15.0"
iOS Device String
"iPod9,1"
"iPhone11,2"
Android specific information about the device.
Android Version String
"1"
"10"
Android Device String
"Google MBOX"
Information about the devices Time Zone
{
"region": "Australia/Adelaide",
"offset": "+1030"
}
{
"region": "Etc/UTC",
"offset": "+0000"
}
{
"region": "America/Los_Angeles",
"offset": "+1030"
}
An offset from UTC time for the time zone in the format +/-HHMM.
Width and Height of the screen when in the "top" interface orientation
The BaseModel provided by Pydantic does not allow for extra properties on the object, this is the opposite behaviour to what we want.
Metadata fields relating to the advert such as viewId, Format & Type, Brand Name, Aspect Ratio ect.
This is not an exhaustive list of all fields. Other fields may be availible but these are guaranteed.
The unique identifier for this Advert View
"311aa2ae-15d9-47e2-813d-170eebc5f980"
The brand that is displayed in this Advertisment, if it exists
The aspect ratio of the Advertisment content
"1x1, 4x5"
"16x9"
An enumeration.
An enumeration.
An enumeration.
The length of the media in seconds
Pretty much everything we write to the ImperfectCSV for each AdView
The ImperfectCSV calculated second by second columns, this object holds all the values for a given second
An enumeration.
An enumeration.
An enumeration.
All the metadata recorded along with each single Frame
The frames index within the Advert View
A UTC ISO 8601 timestamp of when the frame was captured
Same definition as startTimestampHow much time has passed in seconds since the advert initially appeared on sceen
0.6
1.2
2.4
How much time has passed in seconds since the advert initially appeared on sceen. This value is rounded down to the nearest second to assist with grouping data by seconds
0
1
2
Metadata detailing where to find the camera image captured with this frame.
All camera frames are saved to a video file, offaisionally when the system is under strain
they can be skipped entirely.
Path to the video file containing this frame, relative to respondent.dataPath.
The index of the frame within the above video file.
Is there a corrsponding frame in the video file? Or was this video frame dropped?
A catch all dictionary for the shapes of interest in a mobile advert.
Including Screen, Viewport, Header & Footer (Occluding) & Advert shapes.
All ROIs are relative to the top left of the device screen.
A rectange which represents the entire screen. Any coordinate outside of this rectangle should be considered off screen.
A list of points that create the boundary of the polygon. The final point should equal the first in order to create a fully enclosed shape
No Additional ItemsAn object that contains a point in a 2D coordinate system
The x-coordinate of the point.
The y-coordinate of the point.
An object that contains the location and dimensions of a rectangle.
The y-coordinate of the top side of the rectangle.
The x-coordinate of the left side of the rectangle.
The width of the Rectangle.
The height of the Rectangle.
A rectange which represents the viewport, the viewport is the window within the screen where the Application renders it's content I.E. Web Browser or Video Player window
Same definition as SCREEN_RECTA rectange which represents the advert container, many adverts also include extra space surrounding their content on social media sites to include elements like profile pictures, brand headers, a post description, comments ect.
Same definition as SCREEN_RECTA rectangle which represents the advert media/content. This is usually the video or image within the advert, if it is distinguishable from the container.
Same definition as SCREEN_RECTA series of shapes that occlude all other elements on the screen. Any portion
of the advert that intercects with one of these shapes should not be considered visible.
Occluding rects are represented as a list, as there can be more than one occluding rect on the
screen. I.E. Header & Footer
A simple polygon representing an area in a 2D coordinate system.
A rectangular outline of this shape is also provided for convenience.
Same definition as SCREEN_RECTWith all of our collections so far. Adverts displayed on TVs have been full screen. Since we don't do pixel
level gaze estimation, none of the Mobile Region Of Interest
There is the potential for this dictionary to be used in future for other requirements. So it is left empty for now.
The state of the Video content within an advert for a given framme.
Describes the readiness state of the media, based off: [https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/readyState] (https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/readyState)
No information is available about the media resource
Enough of the media resource has been retrieved that the metadata attributes are initialized. Seeking will no longer raise an exception.
Data is available for the current playback position, but not enough to actually play more than one frame.
Data for the current playback position as well as for at least a little bit of time into the future is available (in other words, at least two frames of video, for example).
Enough data is available—and the download rate is high enough—that the media can be played through to the end without interruption.
Was the Video playing when the frame was captured.
Is the video player in fullscreen mode.
How much of the video has played in seconds
The length of the video in seconds
Video player volume between 0 and 1, 0 if muted
Value must be greater or equal to 0 and lesser or equal to 1
The BaseModel provided by Pydantic does not allow for extra properties on the object, this is the opposite behaviour to what we want.
Value must be greater or equal to 0 and lesser or equal to 100
Value must be greater or equal to 0
Value must be greater or equal to 0 and lesser or equal to 100
Value must be greater or equal to 0 and lesser or equal to 100