Gamesight Measurement API
The Measurement API from Gamesight — 3 operation(s) for measurement.
OpenAPI Specification
openapi: 3.1.0
info:
title: Gamesight Measurement API
version: 1.1.0
description: The Gamesight Measurement API ingests a stream of in-game event data with device-level identifiers to power marketing attribution and measurement for PC, console, and web games. Send single events to /events or batches to /events/batch, and manage per-game do-not-track (GDPR/CCPA opt-out) state.
contact:
name: Gamesight Support
email: support@gamesight.io
url: https://docs.gamesight.io/
x-apisjson-source: https://docs.gamesight.io/reference (ReadMe embedded OpenAPI blocks)
servers:
- url: https://api.ingest.marketing.gamesight.io
security:
- ApiKeyAuth: []
tags:
- name: Measurement
paths:
/events:
post:
summary: /events
description: ''
operationId: measurement-api-events
requestBody:
content:
application/json:
schema:
type: object
required:
- type
- user_id
- identifiers
properties:
type:
type: string
description: A name for this type of event. More details [here](https://docs.gamesight.io/docs/additional-events)
default: game_launch
user_id:
type: string
description: A unique identifier for this user. More details [here](https://docs.gamesight.io/docs/rest-api-quick-start#step-2-determine-user-id-value)
default: user123
identifiers:
type: object
description: Details about the device the user is using
required:
- ip
properties:
ip:
type: string
description: User's public IP address
default: 172.123.245.14
os:
type: string
description: User's operating system version. More details [here](#section-os)
default: Windows 7
resolution:
type: string
description: User's screen resolution. More details [here](#section-screen-resolution)
default: 1920x1080
language:
type: string
description: User's ISO 639-1 language string optionally including region. More details [here](#section-language).
default: en
timezone:
type: integer
description: User's timezone as an offset from UTC in minutes. More details [here](#section-timezone).
format: int32
sku:
type: string
description: A custom identifier used to differentiate different distributions of the game
platform:
type: string
description: The platform that the game is running on. More details [here](#section-platform)
platform_device_id:
type: string
description: Device ID for the platform this event was measured on
gsid:
type: string
description: Gamesight GSID value pulled from the Web SDK
useragent:
type: string
description: Browser useragent for events that were sourced from a web browser (not expected for desktop/console events)
country:
type: string
description: Country location for the user (used if you are not providing the IP value)
revenue_currency:
type: string
description: Currency revenue is being reported in
default: USD
revenue_amount:
type: number
description: Amount of revenue being reported. You must pass a revenue_currency together with this field. Can be provided as an Integer, Float or String.
default: 0
format: float
external_ids:
type: array
description: List of external account ids
items:
properties:
external_id_type:
type: string
description: 'Type of external id. Full listing here: https://docs.gamesight.io/reference/measurement-api-events#user-account-ids'
external_id:
type: string
description: The ID from the external platform
scope_type:
type: string
description: 'Allowed values: [''game'', ''org'']. Default value of ''game'' restricts this ID to only be used for attribution within this game.'
scope_id:
type: string
description: Scope id property (when using "org" scope type). If you would like to share IDs between multiple games published by your company, provide your Organization ID here.
sha256:
type: string
description: 'Allowed values: [''server'', ''client'', null]. Control to hashing of external ID prior to storage. null: The ID is stored in plain text. server: The ID is hashed on the server-side before being saved. client: The ID is already hashed in this payload.'
required:
- external_id_type
- external_id
type: object
timestamp:
type: string
description: Explicitly set the timestamp for the event (optional - 2020-01-01T00:00:00)
format: date-time
transaction_id:
type: string
description: Unique transaction ID that is used for deduplicating events, commonly used to ensure idempotency with purchase events. Gamesight enforces that only 1 event will be processed per transaction_id.
gameplay_session_id:
type: string
description: A unique session ID for the user's current game session. Passing this field enables Gamesight to report on session counts, playtime, and actions within a session.
metadata:
type: string
description: Arbitrary metadata to attach to the event. Must be less than 1KB when JSON encoded.
format: json
attribution:
type: array
description: Attribution override to force this event to be attributed to a particular Tracker. Used when working with referral codes
items:
properties:
referral_code:
type: string
description: Referral code used to look up tracker details for attribution
touchpoint_type:
type: string
description: Whether to count this touchpoint as a click or impression
default: click
enum:
- click
- impression
team_id:
type: integer
description: Team hierarchy parameter to associate with this event (required if not providing referral_code)
format: int32
network:
type: string
description: Network hierarchy parameter to associate with this event (required if not providing referral_code)
campaign:
type: string
description: Campaign hierarchy parameter to associate with this event
ad_group:
type: string
description: Ad Group hierarchy parameter to associate with this event
ad:
type: string
description: Ad hierarchy parameter to associate with this event
ad_type:
type: string
description: Ad type reporting parameter to associate with this event
placement:
type: string
description: Placement reporting parameter to associate with this event
keyword:
type: string
description: Keyword reporting parameter to associate with this event
creative:
type: string
description: Creative reporting parameter to associate with this event
site_id:
type: string
description: Site ID reporting parameter to associate with this event
sub_site_id:
type: string
description: Sub Site ID reporting parameter to associate with this event
requested_at:
type: string
description: Time to count the touchpoint at (defaults to 1 second before event time)
format: date
type: object
consent_scopes:
type: object
description: Granular consent settings for these users. Will be merged with consent settings on the Do Not Track endpoint to determine consent settings for this user.
properties:
processing:
type: boolean
description: Represents that this user has consented to data processing. If this is set to `false` then all event payloads for this user will be rejected to prevent any data collection.
attribution:
type: boolean
description: Represents that this user has consented to attribution. If this is set to `false` then events for this user will still be recorded but they won't be attributed to any touchpoints.
postbacks:
type: boolean
description: Represents that this user has consented to their data being posted back to your partner Ad Networks. If this is set to `false` then events for this user will never be used to trigger postbacks.
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value: "{\n \"event\": {\n \"created_at\": \"2120-01-02T13:34:56\", \n \"identifiers\": \"7efa773c803a0..2fbf9a22\", \n \"type\": \"game_launch\", \n \"user_id\": \"b91f8k5r\"\n }\n}"
schema:
type: object
properties:
event:
type: object
properties:
created_at:
type: string
example: '2120-01-02T13:34:56'
identifiers:
type: string
example: 7efa773c803a0..2fbf9a22
type:
type: string
example: game_launch
user_id:
type: string
example: b91f8k5r
'403':
description: '403'
content:
application/json:
examples:
Result:
value: "{\n \"extra\": null, \n \"message\": \"The provided API Key is invalid\", \n \"status_code\": 403, \n \"type\": \"InvalidApiKeyException\"\n}"
schema:
type: object
properties:
extra: {}
message:
type: string
example: The provided API Key is invalid
status_code:
type: integer
example: 403
default: 0
type:
type: string
example: InvalidApiKeyException
'422':
description: '422'
content:
application/json:
examples:
Result:
value: "{\n \"extra\": {\n \"type\": \"required field\", \n \"fake_field\": \"unknown field\"\n }, \n \"message\": \"Input failed validation\", \n \"status_code\": 422, \n \"type\": \"ValidationException\"\n}"
schema:
type: object
properties:
extra:
type: object
properties:
type:
type: string
example: required field
fake_field:
type: string
example: unknown field
message:
type: string
example: Input failed validation
status_code:
type: integer
example: 422
default: 0
type:
type: string
example: ValidationException
deprecated: false
tags:
- Measurement
/events/batch:
post:
summary: /events/batch
description: ''
operationId: eventsbatch
requestBody:
content:
application/json:
schema:
type: object
required:
- events
properties:
events:
type: array
description: A list of event payloads. Max 1000 events per batch
items:
properties:
type:
type: string
description: A name for this type of event.
default: game_launch
user_id:
type: string
description: A unique identifier for this user
default: user123
identifiers:
type: object
description: Device identifiers for the event
required:
- ip
properties:
ip:
type: string
description: User's public IP address
default: 172.123.245.14
os:
type: string
description: User's operating system version. More details [here](#section-os)
default: Windows 7
resolution:
type: string
description: User's screen resolution. More details [here](#section-screen-resolution)
default: 1920x1080
language:
type: string
description: User's ISO 639-1 language string optionally including region. More details [here](#section-language).
default: en
timezone:
type: integer
description: User's timezone as an offset from UTC in minutes. More details [here](#section-timezone).
format: int32
sku:
type: string
description: A custom identifier used to differentiate different distributions of the game
platform:
type: string
description: The platform that the game is running on. More details [here](#section-platform)
platform_device_id:
type: string
description: Device ID for the platform this event was measured on
gsid:
type: string
description: Gamesight GSID value pulled from the Web SDK
useragent:
type: string
description: Browser useragent for events that were sourced from a web browser (not expected for desktop/console events)
country:
type: string
description: Country location for the user (used if you are not providing the IP value)
revenue_currency:
type: string
description: Currency revenue is being reported in
revenue_amount:
type: number
description: Amount of revenue being reported. Can be provided as an Integer, Float or String.
format: float
external_ids:
type: array
description: List of external account ids
items:
properties:
external_id_type:
type: string
description: 'Type of external id. Full listing here: https://docs.gamesight.io/reference/measurement-api-events#user-account-ids'
external_id:
type: string
description: The ID from the external platform
scope_type:
type: string
description: 'Allowed values: [''game'', ''org'']. Default value of ''game'' restricts this ID to only be used for attribution within this game.'
scope_id:
type: string
description: Scope id property (when using "org" scope type). If you would like to share IDs between multiple games published by your company, provide your Organization ID here.
sha256:
type: string
description: 'Allowed values: [''server'', ''client'', null]. Control to hashing of external ID prior to storage. null: The ID is stored in plain text. server: The ID is hashed on the server-side before being saved. client: The ID is already hashed in this payload.'
required:
- external_id_type
- external_id
type: object
timestamp:
type: string
description: Explicitly set the timestamp for the event (optional - 2020-01-01T00:00:00)
format: date-time
transaction_id:
type: string
description: Unique transaction ID that is used for deduplicating events, commonly used to ensure idempotency with purchase events. Gamesight enforces that only 1 event will be processed per transaction_id.
gameplay_session_id:
type: string
description: A unique session ID for the user's current game session. Passing this field enables Gamesight to report on session counts, playtime, and actions within a session.
metadata:
type: string
description: Arbitrary metadata to attach to the event. Must be less than 1KB when JSON encoded.
format: json
attribution:
type: array
description: Attribution override to force this event to be attributed to a particular Tracker. Used when working with referral codes
items:
properties:
referral_code:
type: string
description: Referral code used to look up tracker details for attribution
touchpoint_type:
type: string
description: Whether to count this touchpoint as a click or impression
default: click
enum:
- click
- impression
team_id:
type: integer
description: Team hierarchy parameter to associate with this event (required if not providing referral_code)
format: int32
network:
type: string
description: Network hierarchy parameter to associate with this event (required if not providing referral_code)
campaign:
type: string
description: Campaign hierarchy parameter to associate with this event
ad_group:
type: string
description: Ad Group hierarchy parameter to associate with this event
ad:
type: string
description: Ad hierarchy parameter to associate with this event
ad_type:
type: string
description: Ad type reporting parameter to associate with this event
placement:
type: string
description: Placement reporting parameter to associate with this event
keyword:
type: string
description: Keyword reporting parameter to associate with this event
creative:
type: string
description: Creative reporting parameter to associate with this event
site_id:
type: string
description: Site ID reporting parameter to associate with this event
sub_site_id:
type: string
description: Sub Site ID reporting parameter to associate with this event
requested_at:
type: string
description: Time to count the touchpoint at (defaults to 1 second before event time)
format: date
type: object
consent_scopes:
type: object
description: Granular consent settings for these users. Will be merged with consent settings on the Do Not Track endpoint to determine consent settings for this user.
properties:
processing:
type: boolean
description: Represents that this user has consented to data processing. If this is set to `false` then all event payloads for this user will be rejected to prevent any data collection.
attribution:
type: boolean
description: Represents that this user has consented to attribution. If this is set to `false` then events for this user will still be recorded but they won't be attributed to any touchpoints.
postbacks:
type: boolean
description: Represents that this user has consented to their data being posted back to your partner Ad Networks. If this is set to `false` then events for this user will never be used to trigger postbacks.
required:
- type
- user_id
type: object
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"events": [...Event Ojbects...]}'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Measurement
/games/{game_id}/do_not_track:
put:
summary: /games/{game_id}/do_not_track
description: ''
operationId: do_not_track
parameters:
- name: Authorization
in: header
description: This should be an API Key with the GDPR scope
required: true
schema:
type: string
- name: X-Api-Version
in: header
schema:
type: string
default: 2.0.0
- name: game_id
in: path
description: ID for the Game you want to add the Do Not Track record for
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- user_ids
properties:
user_ids:
type: array
description: List of IDs for users to add to the Do Not Track list
items:
type: string
sha256:
type: string
description: Determines data hashing process. By default all IDs are hashed on the server side before storage. If you would prefer to SHA256 hash data before sending it to the API pass "client"
default: server
consent_scopes:
type: object
description: Granular consent settings for these users. If left to null then all data processing will be blocked for these users.
properties:
processing:
type: boolean
description: Represents that this user has consented to data processing. If this is set to `false` then all event payloads for this user will be rejected to prevent any data collection.
attribution:
type: boolean
description: Represents that this user has consented to attribution. If this is set to `false` then events for this user will still be recorded but they won't be attributed to any touchpoints.
postbacks:
type: boolean
description: Represents that this user has consented to their data being posted back to your partner Ad Networks. If this is set to `false` then events for this user will never be used to trigger postbacks.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"success\": true\n}"
schema:
type: object
properties:
success:
type: boolean
example: true
default: true
deprecated: false
tags:
- Measurement
get:
summary: /games/{game_id}/do_not_track
description: ''
operationId: get_do_not_track
parameters:
- name: Authorization
in: header
description: This should be an API Key with the GDPR scope
required: true
schema:
type: string
- name: X-Api-Version
in: header
schema:
type: string
default: 2.0.0
- name: game_id
in: path
description: ID for the Game you want to add the Do Not Track record for
schema:
type: string
required: true
- name: user_id
in: query
description: List of IDs for users to read from to the Do Not Track list. Pass the `user_id` param multiple times to pull multiple users in a single call.
schema:
type: array
items:
type: string
- name: sha256
in: query
description: Determines data hashing process. By default all IDs are hashed on the server side before storage. If you would prefer to SHA256 hash data before sending it to the API pass "client"
schema:
type: string
default: server
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"optouts\": [\n {\n \"user_id\": \"d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35\",\n \"game_id\": 1,\n \"consent_scopes\": {\n \"attribution\": true,\n \"postbacks\": false,\n \"processing\": false\n },\n \"created_at\": \"2023-01-01T10:12:59\",\n \"updated_at\": \"2023-01-01T10:12:59\"\n }\n ]\n}"
schema:
type: object
properties:
optouts:
type: array
items:
type: object
properties:
user_id:
type: string
example: d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35
game_id:
type: integer
example: 1
default: 0
consent_scopes:
type: object
properties:
attribution:
type: boolean
example: true
default: true
postbacks:
type: boolean
example: false
default: true
processing:
type: boolean
example: false
default: true
created_at:
type: string
example: '2023-01-01T10:12:59'
updated_at:
type: string
example: '2023-01-01T10:12:59'
deprecated: false
tags:
- Measurement
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: A valid Gamesight API key passed in the Authorization header. Reporting API keys carry Reporting, Aggregate Reporting, or GDPR scope.