Configure Your Service Endpoints
Provide configuration details for your media server’s endpoints to a HomePod speaker or an Apple TV.
URL
GET https://cloudextension-testservice.local/api/configurationHeader Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language Required | string | The client’s current user interface language. Your service responds to requests with localized content for this language, if available. |
Cache-Control Required | string | Directives for your service’s caching behavior. |
If-None-Match Optional | ExtensionConfigTag | The identifier of the client’s current configuration information. |
Request-Timeout Required | uint32 | An approximate deadline, in seconds, for processing this real-time user request. |
User-Agent Required | string | The extension protocol running on the client. This is an RFC 7231-compliant string that contains the product name AppleCloudExtension and the SiriKit Extension library version running on the client. |
x-applecloudextension-retry-count Optional | uint32 | The number of previous requests from the client. The client omits this header on the first attempt. |
x-applecloudextension-session-id Required | string | A constant session identifier to include in each request and response. Your service responds to each request with the session ID provided by the client. |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/jose | ExtensionConfig | The request is successful. |
| 304 | Not Modified | The request’s ExtensionConfigTag indicates the client already has the current configuration. |
Discussion
You must cryptographically sign your configuration endpoint response in JSON Web Signature (JWS) format when communicating with the SiriKit Cloud Media API via Media Setup. JWS is part of the JSON Object Signing and Encryption (JOSE) open standard (RFC 7515) that defines a way to cryptographically sign transmitted data.
To generate a signed JWS:
Create the JWS header.
Create the JWS payload.
Sign the JWS.
To create a JWS to communicate with the SiriKit Cloud Media API, use the following fields and values in the header:
Header | Description |
|---|---|
| The algorithm used to sign the JWS. For SiriKit Cloud Media, use |
| Your app bundle identifier registered for the service. |
| The type used by the complete JWS. For SiriKit Cloud Media, use |
| The content type used by the payload of the JWS. For SiriKit Cloud Media, use |
The JWS payload contains JSON-encoded information specific to the SiriKit Cloud Media API and your app, such as intent type, media queues, base URLs for endpoints, and supported API version. The format is defined in the SiriKit Cloud Media OpenAPI Specification. Here are the major keys in the configuration data:
Key | Description |
|---|---|
| (Required) This is a mapping of (abbreviated) Intent names to the SiriKit Cloud Media endpoints and configuration options supported by web endpoint handlers. |
| (Required) This is a mapping of queue API endpoints for the particular configuration valid for the service (or user). |
| The base URL for endpoints. This value can be a fully qualified URL, or a relative URL, used to retrieve this configuration resource. |
| (Required) The supported version of the SiriKit Cloud Media API. |
After creating the JWS, sign it using the Elliptic Curve Digital Signature Algorithm (ECDSA) with the P-256 curve and the SHA-256 hash algorithm. The SiriKit Cloud Media API identifies the intents and media endpoints your service supports by parsing the configuration response. In the decoded JWS below, the service is configured to support the add media, play media, and update media affinity intents, and provides URLs to each as well as the media queue endpoints used to handle intent responses:
{
"alg": "ES256",
"kid": "com.myCompany.appName",
"typ": "JOSE",
"cty": "JSON"
}
{
"intent": {
"addMedia": {
"opt": [
"confirm",
"resolveMediaDestination"
],
"url": "intent/addMedia"
},
"playMedia": {
"opt": [
"resolvePlayShuffled",
"resolvePlaybackRepeatMode",
"resolvePlaybackQueueLocation",
"resolveResumePlayback"
],
"url": "intent/playMedia"
},
"updateMediaAffinity": {
"url": "intent/updateMediaAffinity"
}
},
"media": {
"queues": {
"playMedia": {
"url": "queues/playMedia"
},
"updateActivity": {
"url": "queues/updateActivity"
}
}
},
"version": "1.0.2"
}Regardless of the programming language you’re using with the SiriKit Cloud Media API, there are a variety of open source libraries available online for creating and signing JWS data. Please verify and validate your response before sending it to the SiriKit Cloud Media API.