Device Init

OPTIONS /deviceInit

Purpose

Provides CORS support information for the endpoint.

Responses

Always 200 OK with CORS response headers.

POST /deviceInit

Purpose

Retrieve contextual parameters for content normalization and user context based on a device. This endpoint should be use during the initialization process of API consumers to get information that will required for other API queries. The following actions are performed:

1. A device is selected or created based on the provided deviceId,
2. country location of device is determined based on IP address,
3. livestream access is determined based on IP address and PBS station localization, and
4. Passport status is determined based on PBS Account associated with the device's viewer.

Geolocation (country) and localization (station livestream access) is determined using the PBS Localization API.

Payload

Type

JSON in body.

Parameters

Parameter	Required	Type	Description
deviceId	Yes	String	Unique identifier of a device.
deviceModel	No	String	Device model.
deviceName	No	String	Device name.
deviceType	Yes	DeviceType	Type of device.
stationId	Yes	UUID	ID of the station associated with the device.

ipAddress parameter

Test parameter only

There is an additional parameter ipAddress available in non-production environments only. If set, it will be used instead of the detected IP address. It can be used in local development environments where it is not possible to retrieve an external IP address for a request.

In the production environment, the client IP address is retrieved from the X-Forwarded-For header.

Responses

200 OK

JSON body with the following properties:

• country: ISO 3661-1 alpha-2 of the IP address.
• device
  • deviceId: Unique device ID (matches deviceId from payload).
  • type: Device type (matches deviceType from payload -- does not update).
  • model: Device model.
  • name: Device name.
• ipAddress: IP addressed used for geolocation and localization.
• stationId: Unique station ID (matches stationId from payload).
• viewer
  • id: Unique viewer ID.
  • pbsAccount: PBS Account and membership properties (if available).
    • accountId: PBS Account ID.
    • emailAddress: PBS Account email address (not membership email address).
    • hasLivestreamAccess: Whether the device can access PBS livestreams.
    • hasPassport: Whether the viewer has an active PBS Passport benefit.
    • showVppaScreen: Whether the viewer needs to agree to PBS's VPPA agreement.
  • membershipId: Membership ID from PBS Membership Vault.

400 Bad Request

JSON body with one property:

• reason: Code string indicating the reason for the error:
  • BAD_PAYLOAD: Invalid or malformed payload.
  • IP_ADDRESS_NOT_FOUND: IP address could not be obtained from request.
  • LOCALIZATION_ERROR: Upstream localization provider error.
  • MVAULT_ERROR: Upstream PBS Membership Vault API error.
  • PBS_ACCOUNT_API_ERROR: Upstream PBS Account API error.
  • STATION_NOT_FOUND: Provided stationId not found.
  • UNKNOWN_DEVICE_TYPE: Provided deviceType not valid.

403 Forbidden

Indicates an invalid Origin header was passed in a CORS request.