When a user decides to add your service to their Sonos system, they can authenticate using your iOS or Android app.

This section describes how to implement authentication using either mobile app. Before you read this section, you should understand how to implement authentication using a browser, as described in Add browser authentication. This example builds upon the browser example because your implementation should provide browser authentication as a fallback in case the user does not have your app installed or they are using the Sonos desktop controller.

For app authentication, authentication occurs on your app in between the two API calls getAppLink and getDeviceAuthToken, The app authentication process is summarized as follows:

1. Enable app authentication:
   During the integration and submittal process you enable app authentication so that Sonos processing will include app authentication for your service.
2. Your service returns an app URL for getAppLink:
   The Sonos app uses the API call getAppLink to send information about the user’s Sonos system to your service. Your service responds with an appUrl and appUrlString, which provides custom text the Sonos app presents to the user on the button for opening your app.
3. Your app authenticates the user:
   When the user clicks the button, Sonos opens your app instead of a Web page. The user authenticates on your app and approves the Sonos app for authentication as well. Your app then returns control to the Sonos app by using a callback with inter-app communication.
4. Your service returns a token for getDeviceAuthToken:
   Sonos calls getDeviceAuthToken. Your service returns to the player a token that associates together the authenticated user and Sonos household.

After these steps, the user has your service on their Sonos system.

Enable the app authentication mode

Sonos recommends you implement both the app authentication and the browser authentication modes. To use app authentication, you need to enable this mode by selecting App Link when submitting your integration to Sonos. For more, see Submit your service (the other authentication modes listed are no longer recommended).

To test your app authentication implementation, use the customSD form to choose Application Link in the Authentication SOAP header policy. See Test your service for more details on testing.

Provide an app URL in the getAppLink response

1. From the Sonos app, the user selects your service to add, and then selects Add to Sonos. In this example, the user already has an account with your service.
   
2. The Sonos app sends your service a getAppLink request with information about the user’s Sonos system and a callback path to the Sonos app. See the getAppLink reference page for request input details.
3. Your service constructs the appUrl including the callback as described below.
4. Your service supplies an ID from your strings file in appUrlString. The ID identifies a text string for labeling the button the user selects for launching your app.
5. Your service should also supply details for browser authentication as a fallback in case your app is not installed. See Add browser authentication for details.
6. Your service returns authorizeAccount and sub-elements to the Sonos app.
7. The Sonos app displays a button for the user to select for opening your app. If you supplied a appUrlString value, the button label is a string from your strings file. When the user selects the button, it activates the URL from appUrl.

A sample getAppLink request looks like the following. See the getAppLink reference page for complete details.

Your service’s response to getAppLink should be similar to the following:

Constructing the appUrl

Use the hardware, osVersion, and sonosAppName in the getAppLink request to decide what form the appUrl should be, or if you should return the appUrl at all. Use the following criteria:

• Check the osVersion. If your app does not support this version of the operating system, do not return an appUrl. In this case authentication will fall back to browser authentication.
• Check the sonosAppName to determine on what system the Sonos app is running.
  • if the prefix is ICRU, return a URL to the iOS app in appUrl.
  • if the prefix is ACR, return a URL to the Android app in appUrl.
  • If the prefix is MDCR or WDCR, the Sonos app is on a desktop so do not return an appUrl.
    In this case, the Sonos app processing will fall back to browser authentication.

Include in the appUrl the following additional parameters, which follow the pattern of parameters in an OAuth 2.0 authorization request. For a Sonos appUrl all of these parameters are required.

Parameter	Description
scope	Enter the scope values you define for your service that indicate which parts of the user’s account to access. The Sonos app does nothing with this but pass the scope through to your app.
client_id	Enter the client ID value that represents Sonos to your service. This identifies to your app that the authorization request is from a Sonos system.
response_type	Set this value to code, as required by the OAuth 2.0 specification.
state	Obtain this value from the state parameter supplied in the callbackPath input. The state is an opaque string the Sonos app needs in the callback from your app to determine where to resume. This is especially important if the Sonos app closed and has to restart when the user returns from the app.
redirect_uri	Obtain this value from the base URL in the callbackPath input. This is the Sonos app callback your app uses to return control to Sonos.

The callbackPath in the getAppLink request contains a base URL for the Sonos app and a state parameter, which holds encoded query parameters for the Sonos app. An example callbackPath is as follows:

The redirect_uri (containing the base URL) and the stateparameters pass unchanged through the entire process as follows:

1. From Sonos to your service in the getAppLink request.
2. From your service back to Sonos in the getAppLink response.
3. From Sonos to your app when the app starts up.
4. From your app back to Sonos again in the callback.

appUrl for iOS

Following is an example of a constructed iOS appUrl returned in a getAppLink response:

appUrl for Android

For an Android app you can use implicit or explicit intents in the appUrl. Implicit intents use normal scheme syntax and you pass the desired parameters in the URL. Then, on the Sonos app the parameters are converted into string/string intent parameters. See the iOS example, above.

We recommend explicit intents because they allow you to easily fall back to browser authentication. The following is an example of an Android appUrl returned in a getAppLink response.

At this point you have completed processing for getAppLink.

Callback processing in your app

The Sonos app uses the appUrl that your service provided in the getAppLink response to launch your app. Then when your app is finished authenticating the user, it needs to extract the <callbackPath> from the redirect_uri, add the state parameter, and add a code parameter containing the authorization code obtained from your authentication service. Your app then uses the callback to return control to the Sonos app. The following diagram summarizes the processing required in your app.

1. The user agrees to add their account for your service to Sonos.
   ​
2. The Sonos app launches your app on the user’s device using the appUrl value.
   • On iOS, it uses the standard way to launch an iOS app using the appUrl value.
   • On Android, it uses an intent result with the data in the URI set to the appUrl value.
3. Your app displays to the user a request to grant authorization to Sonos using whatever steps you choose, such as have the user enter their password to enable access.
4. Your app extracts values from the URL parameters.
5. Your app obtains an authorization code from your authentication service to grant access to Sonos. Sonos uses the code later to obtain the access token with a getDeviceAuthToken request.
6. Your app sets a code parameter to the authorization code and sets a state parameter to the value from the input URL’s state parameter.
7. Your app constructs the callback URL using the extracted redirect_uri value and adds code and state URL parameters.
8. Your app uses the Sonos iOS callback appUrl URL or Android intent’s result to send the user back to the Sonos app.

The callback URL must be the same value returned in the appUrl of the getAppLink result.

Then add the following additional URL parameters:

Parameter	Type	Required	Description
code	string	Required	The authorization code obtained from your authentication service.
state	string	Required	The state parameter that was sent when your app was invoked by the Sonos app.
nickname	string	Optional	Your app can provide a nick name, which Sonos uses to pre-populate the Name field in the setup wizard. However, the user can choose to override the nickname. Although you can provide the nick name here from your app, we recommend you provide it in your service’s response to getDeviceAuthToken, which works for both app and browser authentication.
errorCode	int	Optional	An error code value greater than 0. This should rarely be needed except for internal debugging. If you design your service to minimize errors when constructing the appUrl, there should be minimal errors in the input parameters when the Sonos app invoked your app.
errorMessage	string	Optional	The ID for the error message string (in your strings.xml file), which is displayed to the user in the Sonos account setup wizard. Used with the errorCode parameter.

Constructing the Callback URL for an iOS App

The following is a sample of a callback URL for iOS:

Constructing the Callback URL for an Android ApP

On Android devices, instead of a callback URL, you use intents. When your app has finished all necessary steps, it should use putExtra(String, bundle) for the required parameters and any optional parameters. The required parameter keys to be included in the intent are the following:

• com.sonos.MusicServicesWizard.extras.callbackPath
• com.sonos.MusicServicesWizard.extras.code
• com.sonos.MusicServicesWizard.extras.state

The optional keys for the intent are the following:

• com.sonos.MusicServicesWizard.extras.nickname
• com.sonos.MusicServicesWizard.extras.errorMessage

The Sonos app expects the values to come back in the Intent parameter of onActivityResult(). For example:

If the returnCode is greater than 0, Sonos will use the string com.sonos.MusicServicesWizard.extras.errorMessage.

Respond to getDeviceAuthToken with the authorization token

After your app authenticates the user and returns control to the Sonos app, the following process flow occurs:

1. The Sonos app sends to the Sonos player a request to add an account.
   
2. The Sonos player sends your service a getDeviceAuthToken request with the householdId and linkCode.
3. Your service requests authorization be granted by making a request with the linkCode to your Authentication service.
4. The Authentication service returns an authorization token to use for authorization. You can use any format you wish for authorization tokens using up to 2048 characters. Your service must be able to decode the user from the token so that it can perform actions on the correct account, such as setting a user favorite. if a user connects to more than one Sonos household, your service must use a different token to represent that user-household combination.
5. Your service can optionally set the nickname and userIdHashCode value.
   • Your service can provide a nick name, which Sonos uses to pre-populate the Name field in the setup wizard. However, the user can choose to override the nickname.
   • Your service can provide a hash code, which Sonos uses to verify the account is unique and not being added to Sonos again.
6. The player verifies the account with the hash code and creates the account.
7. Finally the Sonos app displays a message to the user that your service has been added to Sonos.

For details and an example, see the section, Success Response to getDeviceAuthToken in Add browser authentication.