ZeroConf API

The Spotify Connect ZeroConf API is an HTTP interface used for announcing and securely logging in to a hardware device. It enables a Spotify client, such as an iOS or Android device, to perform a login to a hardware device without the user entering a password.

The server providing the ZeroConf API can either be running inside the eSDK itself, or be implemented by a Spotify hardware partner. If the builtin ZeroConf server is enabled (see SpConfig::zeroconf_serve) and working satisfactorily on the hardware device, no ZeroConf implementation is needed from the Spotify hardware partner. Otherwise, it must be implemented to support the Spotify Connect feature.

Implementing the ZeroConf API, when not using the internal builtin ZeroConf service, requires:

• a HTTP server
• a JSON encoding and decoding library
• a mDNS discovery service compatible with Apple's Bonjour.

The partner must then implement the behavior described in this document and hook it up appropriately with the calls to the Spotify Embedded API and their own integration code.

If SSL is supported by the web server, the ZeroConf API should be accessible via HTTPS. When HTTPS is enabled, it is preferred that non-secure HTTP access is disabled.

This is the ZeroConf process:

• The Spotify desktop/smartphone client and the hardware device connect to the same network.
• The device's ZeroConf API service is discovered by the client using a service discovery protocol.
• The client logs in to the device using the ZeroConf API via HTTP.
• The device is now ready to be used with Spotify Connect!

The hardware device must use mDNS/DNS-SD in a way compatible with Apple's Bonjour, to advertise its IP address, the port of its HTTP service, and the path to the ZeroConf API implementation on the web server.

The DNS-SD service type is _spotify-connect._tcp.

• A SRV record should be specified with the IP address and port
• A TXT record should be provided with CPath=<path to ZeroConf implementation>. If a ZeroConf implementation is reachable on http://host:port/zeroconf, the TXT record shall be CPath=/zeroconf.

See the appendix for error codes and corresponding error strings.

• Requests are made over HTTP using the GET or POST method.
  • All requests are answered by a response.
  • Every valid request has the action variable.
  • The application/x-www-form-urlencoded encoding is used for POST requests.
• Responses are JSON objects (with Content-Type: application/json).
• HTTP status code should match corresponding status from HTTP Status section.
• All strings must support UTF-8 character encoding. All strings returned by the Spotify Embedded SDK will be in UTF-8 encoding.
• If requests are handled on their own thread, keep in mind that the Embedded SDK is not thread-safe. You need to ensure that no two threads invoke SDK APIs at the same time. See threading.
• If ZeroConf is turned off on a device that is inactive (ie a slave in a multiroom configuration), mDNS should be turned off. It's not enough to just turn off the webserver endpoints - they will still be hit by clients, spending unnecessary effort.

Mandatory fields in all responses:

Success example:

Failure example:

The API does not use any passwords. Only the user name and credentials blob are needed when logging in to Spotify.

Login should be performed by calling SpConnectionLoginZeroConf() with the data in this message.

Before sending a response, the application must do the following:

• If a user's credentials are already stored, the existing user must be logged out using SpConnectionLogout() and the stored data must be deleted from persistent storage (same as resetusers resetUsers request).
• Verify that SpConnectionLoginZeroConf() returns #kSpErrorOk (and fail the request if it returns something else).
• Verify that login is successful by waiting for the #kSpConnectionNotifyLoggedIn event (and fail the request if SpCallbackError() is invoked).

The encrypted blob received in this ZeroConf message must not be saved. On a successful login, the SpCallbackConnectionNewCredentials() callback will be invoked with the credentials to save to persistent storage.

The user's credentials must not be saved to persistent storage unless the login is successful.

The status must not be returned until a #kSpConnectionNotifyLoggedIn or SpCallbackError() event is received.

If any required field is not specified, the response must be an error of type InvalidArguments, and the login function must not be called.

HTTP method: POST.

Extra parameters:

Return: only status.

HTTP method: GET.

Extra parameters:

Return:

[1]Note The application is responsible for properly escaping special characters in the strings returned by SpZeroConfGetVars before sending them as part of the JSON response. See the JSON standard for the requirements.

[2]Note Other Spotify clients may present brandDisplayName and the optional modelDisplayName to the user in the Connect menu and in other places. These strings may contain UTF-8 characters. The limitations of SpConfig::brand_name and SpConfig::model_name do not apply. However, during the certification process, we will verify that the fields are set to reasonable values that do not confuse users and can be displayed correctly by other Spotify clients.

Example:

Request:

Response from device without aliases. The field "remoteName" defines the name to be displayed for the device.

Response from a device using device aliases. In this case, the field remoteName should be empty in the response as the displayed name for respective alias is defined in the aliases field.

The currently logged in user (if any) should be logged out using SpConnectionLogout. All user credentials should be deleted from the device's local storage. Any other persistent data related to ZeroConf should be cleared to factory-reset defaults.

HTTP method: POST.

Extra parameters: none.

Return: only status.

Using ZeroConf, it is possible to announce multiple "virtual devices" from a device. This allows the eSDK device to expose, for instance, multiroom zones as ZeroConf devices.

Note There is no built-in support for multiroom audio forwarding in the eSDK. This feature enables an integration to announce partner supplied multiroom audio routing configurations directly in the Spotify app.

Device aliases will show up as separate devices in the Spotify app. When a device is selected for playback, you will know which alias from the device_alias_index parameter in the SpCallbackSelectedDeviceAliasChanged callback.

If the built-in ZeroConf server is used, there is already support for device aliases, up to a maximum of SP_MAX_DEVICE_ALIASES. Simply configure the alias names in SpConfig::device_aliases,

for example:

When using SpConfig::device_aliases, SpConfig::display_name is not used.

The following table shows the different responses returned by the HTTP server to a client's request:

[1]Note It is permissible to send HTTP status code 200 in all cases, as long as a valid JSON reply is returned that contains the status, statusString, and spotifyError strings.