getAppLink
Sonos uses getAppLink
to authenticate users so they can use your service. See Add authentication for details. Sonos makes this request on your secure (HTTPS) endpoint.
Request parameters
Only the householdId
has a maximum value defined.
Name | Type | Description |
---|---|---|
householdId | string(255) | The Sonos household ID requesting the link code. |
hardware | string | The device type and model as reported by the platform. |
osVersion | string | The OS version as reported by the platform. |
sonosAppName | string | The name of the Sonos app issuing the request. |
callbackPath | string | The callback URL your service uses to launch Sonos after your app has authenticated the user. |
Response
Include the response in a getAppLinkResult
inside a getAppLinkResponse
element.
Name | Type | Description |
---|---|---|
authorizeAccount | complex | getAppLinkResult must have the authorizeAccount element. The Sonos app uses the information in authorizeAccount to add or reauthorize an account. The data determines if the Sonos app sends the user to your native mobile app for authentication or uses a web page as a fallback for authentication.The Sonos app uses the data you provide in the sub-elements appUrl and appUrlStringId to allow the user to open your iOS or Android app.In the case of a failure when the user tries to open the URL in appUrl , the Sonos app falls back to browser authentication. Browser authentication uses the information you provide in deviceLink to send users to a web page for authentication. |
createAccount | complex | (Optional) Include the createAccount element in your response so that the Sonos app can provide the user with "onboarding" scenarios such as creating an account or creating a trial account for your service.The Sonos app uses the data you provide in the sub-elements appUrl and appUrlStringId to allow the user to create an account.In the case of a failure when the user tries to open the URL in appUrl , the Sonos app sends users to the sign-in URL you provided in the version manager. |
callToAction | complex | callToAction is deprecated. |
installAction | complex | installAction is deprecated. |
authorizeAccount & createAccount
The following elements are sub-elements of the authorizeAccount
and the createAccount
elements.
Name | Type | Description |
---|---|---|
appUrl | string(2048) | (Optional) The URL to open your app, which the Sonos app associates with a button displayed to the user. You can omit the appUrl if you use the deviceLink element for a web page.If you wish to send the user to a web page instead of an app, leave out the appUrl element. When you leave this out:- For authorizeAccount , return the required values in the deviceLink element.- For createAccount , Sonos will use the sign-in URL you provided in the version manager. |
appUrlStringId | string | The ID of a string that the Sonos app uses to label the button linked to the appUrl . |
deviceLink | complex | (Optional, but Recommended) Provides the web page information for authentication. For example, Sonos uses deviceLink for authentication when a user doesn't have your app installed on their device. |
failureStringId | string | (Optional) The ID of a string that Sonos uses to message the user if Sonos fails to open the appUrl . |
failureUrl | string(2048) | (Optional) A URL where users can go to get support or find out more about what might possibly be wrong. The Sonos app includes this link with the failureStringId message. |
failureUrlStringId | string | (Optional) The ID of a string to use as a label for the failureUrl link. |
deviceLink
Name | Type | Description |
---|---|---|
regUrl | string | A URL that a user should navigate to in order to complete device authentication. Be sure that this page handles script injection. |
linkCode | string | An authorization code that players use to obtain access and refresh tokens for your service. |
showLinkCode | boolean | Determines whether the Sonos app displays the link code or not. If true, the app displays the link. If false, it does not. |
linkDeviceId | string | (Optional) A token, hidden from the user to prevent token phishing. The player will send this back in the getDeviceAuthToken request. Use the linkDeviceId to ensure that the device you originally gave the token to is the same device sending you the request. |
Details
- Be sure to enable Application Link authentication in the version manager.
- When testing your integration, enable app link authentication on the customSD page. See Test your service for details.
- In your response, add the
callbackPath
element received in thegetAppLink
request as aredirect_uri
parameter to theappUrl
element. When the Sonos app uses theappUrl
value to launch your app, it also contains the URL back to the Sonos app. Once your app finishes authenticating the user and authorizing Sonos, your app uses the Sonos callback URL to return control to Sonos. On Android devices, instead of a callback URL, we use intents. For details about the Sonos callback path, see Add app authentication.
Sample request with HTTP headers
The Sonos app sends your service a request such as the following:
CONNECTION: close
ACCEPT-ENCODING: gzip
HOST: smapi.acme.com
USER-AGENT: Linux UPnP/1.0 Sonos/31.3-20100 (ICRU_iPhone3,1); iOS/Version 6.1.3 (Build 10B329)
CONTENT-LENGTH: 520
CONTENT-TYPE: text/xml; charset="utf-8"
SOAPACTION: "http://www.sonos.com/Services/1.1#getAppLink"
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
<s:Header>
<credentials xmlns="http://www.sonos.com/Services/1.1">
<deviceId>B8-E9-37-C0-01-18:0</deviceId>
<deviceProvider>Sonos</deviceProvider>
</credentials>
</s:Header>
<s:Body>
<getAppLink xmlns="http://www.sonos.com/Services/1.1">
<householdId>Sonos_4czgmbzy91wJnRf8VuKB0eYPyF_1405dcfa</householdId>
<hardware>Android 7,2</hardware>
<osVersion>Version 7.2</osVersion>
<sonosAppName>ACR_Nexus7,2</sonosAppName>
<callbackPath>sonos://x-callback-url/addAccount?state=sid%3D55555%26OAuthDeviceID%3DSonos_household%26callbackPath%3D%2FaddAccount</callbackPath>
</getAppLink>
</s:Body>
</s:Envelope>
Sample response — OS supported, HTTP headers omitted
If AppLink supports the request hardware
and osVersion
, your service returns at least the authorizeAccount
element. The Sonos app takes your response and identifies a link and button text to present to the user. Your app can also return the createAccount
element. This element identifies link and button text for the Sonos app to present to the user for creating an account.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<getAppLinkResponse xmlns="http://www.sonos.com/Services/1.1">
<getAppLinkResult>
<authorizeAccount>
<appUrl>acme://open/authorizeSonos;redirect_uri=sonos://x-callback-url/addAccount?state=sid%3D55555%26OAuthDeviceID%3DSonos_household%26callbackPath%3D%2FaddAccount</appUrl>
<appUrlStringId>LAUNCH_ACME_APP</appUrlStringId>
<deviceLink>
<regUrl>https://acme.sonos.com/deviceLink/home?linkCode=55AA5</regUrl>
<linkCode>55AA5</linkCode>
<showLinkCode>false</showLinkCode>
</deviceLink>
</authorizeAccount>
<createAccount>
<appUrl>acme://open/createAccount</appUrl>
<appUrlStringId>CREATE_ACCOUNT</appUrlStringId>
</createAccount>
</getAppLinkResult>
</getAppLinkResponse>
</s:Body>
</s:Envelope>
Sample response — OS not supported, HTTP headers omitted
The Sonos app will authenticate your service using deviceLink
if your app doesn't support the request hardware
or osVersion
.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<getAppLinkResponse>
<getAppLinkResult>
<authorizeAccount>
<appUrlStringId>SIGN_IN</appUrlStringId>
<deviceLink>
<regUrl>https://acme.sonos.com/deviceLink/home?linkCode=55AA5</regUrl>
<linkCode>55AA5</linkCode>
<showLinkCode>false</showLinkCode>
</deviceLink>
</authorizeAccount>
<createAccount>
<appUrlStringId>CREATE_ACCOUNT</appUrlStringId>
</createAccount>
</getAppLinkResult>
</getAppLinkResponse>
</s:Body>
</s:Envelope>
Updated 12 months ago