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 the getAppLink request as a redirect_uri parameter to the appUrl element. When the Sonos app uses the appUrl 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>