Pairing Service API

setupPairing, 

To begin using the pairing service, please first contact us to configure your API access.

API Overview

1.0.1 Common Response Parameters:

  • method
    1. indicates the method that was consumed, such as getDeviceToken or pairDevice
  • status
    1. 0 indicates success
    2. non-zero response such as 1 indicates that there was a problem with the request.
  • error
    1. When status is non-zero, “error” will be present in the response with a human readable version of the error that occurred.
  • generation_time
    1. Useful for isolating bottlenecks end-to-end, the amount of time the method took to execute on the server
  • message
    1. This response parameter should not be used for programmatic comparisons, it is intended for debugging purposes and may help those integrating with the pairing API to identify issues.

1.0.2 Response Headers

Reponse headers can give insight into the response, the following headers ARE used, and if your client device supports cookies, a session cookie will be used.

  • Header: content-type
    1. application/xml, application/json, text/plain
    2. utf-8
  • Header: connection
    1. Keep-Alive is not expected to result in an actual keep-alive, normal responses close the connection.
  • Header: HTTP Status Codes - “HTTP/1.0 OK”, and other HTTP/1.0 codes are used to communicate when a standard error type occurs (or success) including:
    1. 200 – OK (HTTP/1.0 OK)
      • Authentication parameters/method accepted. Request is authorized and response present.

    1. 401 – unauthorized (HTTP/1.0 Unauthorized)
      • check any “key” parameters you sent (relay_key or auth_key), as this method requires a valid key to process.

      • The body of the response will still be valid JSON or XML as requested in all cases EXCEPT WHEN THE REQUEST IS DIRECTLY RESPONDED TO BY THE WEB SERVER and misses the web service entirely, such as is the case when Apache does not fulfill a request.

Some 200 messages do not have a communication level error, but in the context of the desired response an error may be present such as “no such token found”. In this case, the developer will need to rely on the response body’s “status” and “error” parameters to handle errors gracefully.

  • Caching (request – “If-Modified-Since”, response – “Last-Modified”)
    1. Currently caching is supported by the code base but not implemented in any of the existing methods, through the use of an “If-Modified-Since” header in the request. The pairing service response will contain a usable “Last-Modified” header if the response is cacheable, that you should keep track of for populating the If-Modified-Since header in future requests if that method supports it.

1.1 getPairingToken (Consumer = AV Application)

Given a device_id for any set top box, retrieve a long-lived token (to use with the relay service) and a set of pairing_key parameters that allow the application to present a user with a short lived key that can be used to obtain the long-lived token.

Note: (*) = required

1.1.1 Request Parameters

Parameter

Type

Description

device_id

String*

Within stitcher session, the application would know of this as being “session.device_id”. String – obfuscated hash that persists between applications…

service_alias

String*

Pre configured pairing service ID, allows multiple deployments and/or applications to be registered on the pairing server within multiple “services”, such as a generic AV service and one specific to 1 app. Configurable per service area.

auth_key

String*

Must match the pairing server auth_key for the provided service_alias. This will ensure that only ActiveVideo applications may initiate pairings with the pairing service.

user_agent

String*

A string representation of the user agent which is requesting the pairing key. Ex: “AVDK1.4.1-webremote0.4 rev 3

minimum_validity

Int (optional, default=100)

Force pairing service to return a key which is valid for at least this many seconds, use this to control the recycling of keys when it could present an awkward use case for consumers – so they always have a known amount of time to pair once obtaining the pairing_key.

1.1.2 Response Parameters

Parameter

Type

Description

method

String*

See 1.0.1

generation_time

String*

See 1.0.1

status

Int*

See 1.0.1

pairing_token

String

The pairing token that the trusted device should use to connect to the relay service.

pairing_index

Int

The order of the pairing token in all historical pairings, so “3” would indicate that including the device this pairing is paired to, the pairing is the 3rd pairing historically.

pairing_key

String

A key that can be used with the pairDevice method to obtain a pairing_token for this device_id.

pairing_key_expires_in

Int

To avoid confusion with changes of dates between date zones, this response parameter merely reflects the time in seconds until the pairing_key will become “EXPIRED” and unusable.

relay_url

String

The URL of the relay server to which you should connect to initiate message relaying through web sockets.

JSONXML

 

1.2 pairDevice (Consumer = 3rd party device)

Provided a pairing key will generate a long-lived pairedPairing_token that the 3rd party consumer (iphone, web remote, etc) can use with the relay server through the life of the pairing.

1.2.1 Request Parameters

Parameter

Type

Description

pairing_key

String (required)

A string which is obtained by the WebRemote.js library from pairingService::getPairing_token(), displayed to the user, and then sent in this request from a 3rd party device.

pairing_name

String (required)

In order for the AV application to present the user with a list of paired devices to manage, we MUST acquire a name to give this pairing at the time of pairing. The iphone app or other 3rd party application can provide default names, but should manage capturing of this field and sending to the Pairing Service API at pairing time.

user_agent

String (optional)

A string representation of the user agent which is requesting the pairing key. Ex: “iOS4.0.2-comcast-xFinity remote rev 2

1.2.2 Response Parameters

Parameter

Type

Description

method

String

See 1.0.1

generation_time

String

See 1.0.1

status

Int

See 1.0.1

pairing_token

String

Long-lived token which can be used indefinitely (unless revoked) to communicate with other paired devices.

relay_url

String

URL to connect to in order to begin communicating with other devices.

JSON/XML

 

1.3 getTokenInfo (Consumer = Relay Service)

Provided a pairedPairing_token return information pertaining to the unique pairing (if it exists), and gives the relay server access to a method by which it can determine the status of the authenticity of the request. This request is a “yes”/”no” method, where the requestor would use this method only to determine if the pairing_token it has been presented is active and can be allowed to proceed. The “is_valid” response parameter is always present and should be compared to the integer 1 for “yes”. A bad “relay_key” is sufficient reason to receive a 401 – Unauthorized response.

1.3.1 Request Parameters

Parameter

Type

Description

relay_key

String (required)

Must match the global relay_key that has been established for the communication between relay service and pairing service.

pairing_token

String (required)

The device token to retrieve information about.

1.3.2 Response Parameters

Parameter

Type

Description

method

String

See 1.0.1

generation_time

String

See 1.0.1

status

Int

See 1.0.1

is_device

Int

A Boolean integer, where 1 indicates that the pairing originated from the ActiveVideo device itself, and should be treated as the target of messages sent from remote devices. While 0 indicates that the device is not an ActiveVideo device, but a remotely paired device.

pairing_name

String

The name the remote device called itself initially when pairing

pairing_index

Int

The order of the pairing token in all historical pairings, so “3” would indicate that including the device this pairing is paired to, the pairing is the 3rd pairing historically.

pairing_status

String

One of ACTIVE, REVOKED, INVALID

device_id

String

The device id that identifies which set top pairing keys/tokens are associated with. Allows for a “group” of pairings which are able to communicate via relay service with each other for this device.

message

String

If the pairing_token in question is not valid, this parameter will indicate why to the human reader for debugging purposes. 

is_valid

Int

A Boolean integer, where 1 indicates that the pairing IS GOOD/ACTIVE, and 0 indicates it is invalid/NOT ACTIVE. The requestor can proceed to allow a device using this pairing_token to communicate with the device if is_valid == 1.

JSON/XML

 

1.4 getRelay (Consumer = AV Application & 3rd party device)

Provided a pairedPairing_token return information pertaining to the unique pairing (if it exists), and gives the relay server access to a method by which it can determine the status of the authenticity of the request. The relay_url will itself contain the pairing_token in the response, no alteration is required – can connect to the relay_url directly to begin relaying messages.

1.4.1 Request Parameters

Parameter

Type

Description

pairing_token

String (required)

The device token for which you would like to locate the relay_url.

1.4.2 Response Parameters

Parameter

Type

Description

method

String

See 1.0.1

generation_time

String

See 1.0.1

status

Int

See 1.0.1

relay_url

String

URL to connect to in order to begin communicating with other devices.

JSON/XML 

1.5 getPairedDevices (Consumer = AV Application)

Provided a pairedPairing_token return information pertaining to the unique pairing (if it exists), and gives the relay server access to a method by which it can determine the status of the authenticity of the request.

1.1.1 Request Parameters

Parameter

Type

Description

device_id

String

Within stitcher session, the application would know of this as being “session.device_id”. String – obfuscated hash that persists between applications…

service_alias

String

Pre configured pairing service ID, allows multiple deployments and/or applications to be registered on the pairing server and be differentiated

auth_key

String

Must match the pairing server auth_key for the provided service_alias. This will ensure that only ActiveVideo applications may initiate pairings with the pairing service.

1.1.2 Response Parameters

Parameter

Type

Description

method

String

See 1.0.1

generation_time

String

See 1.0.1

status

Int

See 1.0.1

paired_devices_count

Integer

The number of devices associated with the requested device_id (non-inclusive of the trusted pairing identifying the AV Device itself).

paired_devices

Array ([

   String pairing_token,

   Int pairing_index,

   String pairing_name,

   String pairing_status,

   String pairing_pin,

])

An array/object made up of objects per pairing that tell the pairing_token (used to revoke pairings), the order of the pairing token in all historical pairings, the name the remote device called itself initially when pairing, and the status of that pairing (only “ACTIVE” pairings are returned currently), and any pin set using updatePairing.

JSON/XML

 

1.6 revokePairing (Consumer = AV Application)

Provided a pairing_token, change the status of the pairing to “REVOKED” so that it cannot be used in future requests.

1.6.1 Request Parameters

Parameter

Type

Description

device_id

String

Within stitcher session, the application would know of this as being “session.device_id”. String – obfuscated hash that persists between applications…

service_alias

String

Pre configured pairing service ID, allows multiple deployments and/or applications to be registered on the pairing server and be differentiated

auth_key

String

Must match the pairing server auth_key for the provided service_alias. This will ensure that only ActiveVideo applications may initiate pairings with the pairing service.

pairing_token

String

The device token for which you would like to locate the relay_url.

1.6.2 Response Parameters

Parameter

Type

Description

method

String

See 1.0.1

generation_time

String

See 1.0.1

status

Int

See 1.0.1

message

String

Provides readable success message upon removing the pairing.

JSON/XML

1.7 updatePairing(Consumer = AV Application)

Provided a pairing_token, change an allowed field within the pairing such as the pairing_pin.

1.7.1 Request Parameters

Parameter

Type

Description

service_alias

String

Pre configured pairing service ID, allows multiple deployments and/or applications to be registered on the pairing server and be differentiated

auth_key

String

Must match the pairing server auth_key for the provided service_alias. This will ensure that only ActiveVideo applications may initiate pairings with the pairing service.

pairing_token

String

The device token for which you would like to locate the relay_url.

pairing_pin

String(optional)

Maximum 20 characters, a pin made up of any alphanumeric sequence to be associated with this pairing.

username

Stri ng (optional)

Associate this pairing with a user account based on username. If successful, the response updated_fields will contain the matching numeric user_id. MUST N OT BE A DEVICE pairing_token, only 3rd party pairing_token can be associated with a user.

1.7.2 Response Parameters

Parameter

Type

Description

method

String

See 1.0.1

generation_time

String

See 1.0.1

status

Int

See 1.0.1

message

String

Provides readable success message upon removing the pairing.

updated_fields

Array ([

nameOfField:valueOfField,

])

An array of key/value pairs representing the successfully set values you provided. Currently only pairing_pin or user_id.

 

 

  • Friday, 12 August 2011
  • Tags: APIs
  • Number of Views: 6015

Your destination to find out more about just how easy it is to develop advanced applications that leverage the “write-once, deploy-everywhere” content creation environment of ActiveVideo’s CloudTV™ platform. You will be able to significantly reduce app time-to-market for connected devices of all types, as well as cable settop boxes that have no additional connectivity. Manufacturers and virtual service providers, as well as cable and IPTV operators around the world are currently benefiting from the advantages of ActiveVideo’s CloudTV platform.

© 2019 Active Video Networks. All Rights Reserved