Step 4: Make an Authorization Request from Your App

In this example, the app gets both the Alexa app URL and the LWA fallback URL.

import Alamofire
import SwiftyJSON

class AlamofireHelper {

    // Your backend base URL from which you're requesting the URL
    static let BASE_URL = "https://exampleBackEndURL"
    
    /*! Get Alexa app Universal Link and LWA fallback URL
     @param userAccessToken for your backend server
     @param state maintained between client and server, caller should generate it 
     */
    static func getAlexaAppUrl(userAccessToken:String, state: String) -> DataRequest {
        let alexaAppUrl = "/alexaurl"
        let inputstate = "?state=" + state
        
        var urlRequest = URLRequest(url: URL(string: BASE_URL + alexaAppUrl + inputstate)!)
        urlRequest.addValue("Bearer " + userAccessToken, forHTTPHeaderField: "Authorization")
        return Alamofire.request(urlRequest)
    }
    
    private init() {}
}

// Call to your backend to get the authorization request URLs (Alexa app / LWA)
AlamofireHelper.getAlexaAppUrl(userAccessToken: savedSession.accessToken, state: StateHelper.generateState()).responseJSON {
    response in
    guard let status = response.response?.statusCode, 200..<300 ~= status else {
        self.createAlert(title: "Failed to get Alexa URL", message: "Failed to get Alexa URL")
        return
    }
    guard let responseValue = response.result.value else {
        self.createAlert(title: "Invalid response", message: "Invalid response")
        return
    }
    let reponseInJSON = JSON(responseValue)
    guard let companionApp = reponseInJSON["companionAppURL"].string,let lwaFallback = reponseInJSON["LWAFallBackURL"].string else {
        self.createAlert(title: "Error response", message: "Error response")
        return
    }
    guard let companionAppURL = URL(string: companionApp), let lwaFallbackURL = URL(string: lwaFallback) else {
        self.createAlert(title: "Incorrect URL format", message: "Incorrect URL format")
        return
    }
    // The openUniversalLinks code snippet can be found in another example
    self.openUniversalLinks(companionAppURL: companionAppURL, lwaFallbackURL: lwaFallbackURL)
}

In this example, the app opens the Alexa app URL or, the LWA fallback URL if the Alexa app isn't installed.

Note the following:

• This example uses the UIApplication.shared.open API to open the URL with the universalLinksOnly option.
• URLs only open when there is an app (in this case, the Alexa app) that's configured to handle Universal Links with the universalLinksOnly option. You can therefore pass closure expressions in completionHandler to handle the case in which the Alexa app doesn't launch (for example, the Alexa app wasn't installed or is a version that doesn't support Universal Links).
• If your app isn't able to launch the Alexa app when using the universalLinksOnly option, your app needs to get the Amazon authorization code by using LWA. For the LWA Fallback URL format, see URLs and endpoints. You can use SFAuthenticationSession on iOS 11 or ASWebAuthenticationSession on iOS 12.0 or higher. This gets the Safari user session and cookies, which avoids an extra login when the user is already logged in to Amazon.com on Safari. This will cause your app to display a window that asks the user's consent to share website information. iOS defines the content of the consent message.
• For iOS versions below 11.0, this example uses SFSafariViewController to send users to the LWA page. The SFSafariViewController doesn't ask for the user's consent to share website information; the Safari browser therefore doesn't share cookies with the SFSafariViewController.

import SafariServices

// Open the Alexa URL with option universalLinksOnly
// If it doesn't open the Universal Link, open the LWA fallback 
private func openUniversalLinks(companionAppURL: URL, lwaFallbackURL: URL) {
    UIApplication.shared.open(companionAppURL, options: [UIApplication.OpenExternalURLOptionsKey.universalLinksOnly:true]) {
        companionAppLaunched in
        if !companionAppLaunched {
            if #available(iOS 12.0, *) {
                WebSession.initWebAuthenticationSession(authURL: lwaFallbackURL)
            } else if #available(iOS 11.0, *) {
                WebSession.initAuthenticationSession(authURL: lwaFallbackURL)
            } else {
                let safariViewController =  SFSafariViewController(url: lwaFallbackURL)
                self.present(safariViewController, animated: true, completion: nil)}
        }
    }
}

// Web session
class WebSession {
    @available(iOS, introduced: 11.0, deprecated: 12.0)
    private static var authenticationSession: SFAuthenticationSession?
    
    @available(iOS 12.0, *)
    private static var webAuthenticationSession : ASWebAuthenticationSession?
    
    private static let CALLBACK_URL_SCHEME = "https://yourAppsUniversalLinkURL"
    
    @available(iOS, introduced: 11.0, deprecated: 12.0)
    static func initAuthenticationSession(authURL:URL) {
        if let session = authenticationSession {
            session.cancel()
        }
        self.authenticationSession = SFAuthenticationSession.init(url: authURL, callbackURLScheme: CALLBACK_URL_SCHEME, completionHandler:{
            (callBack:URL?, error:Error?) in
            //Callback and error handling
        })
        self.authenticationSession?.start()
    }
    
    @available(iOS 12.0, *)
    static func initWebAuthenticationSession(authURL:URL) {
        if let session = webAuthenticationSession {
            session.cancel()
        }
        
        self.webAuthenticationSession = ASWebAuthenticationSession.init(url: authURL, callbackURLScheme: CALLBACK_URL_SCHEME, completionHandler:{
            (callBack:URL?, error:Error?) in
            // Callback and error handling
        })
        self.webAuthenticationSession?.start()
    }
    
    private init(){}
}

For websites, and as a fallback for when the Alexa app isn't installed on the iOS device, open the LWA URL. In this example, the app opens LWA in a view controller.

import SafariServices

// Open Login with Amazon in Safari View controller
private func openSafariView(lwaFallbackURL: URL) {
    let safariViewController =  SFSafariViewController(url: lwaFallbackURL)
    self.present(safariViewController, animated: true, completion: nil)
}

In this example, the app validates and extracts the parameters from the call that the Alexa app made to its Universal Link.

// Handler for Universal Links in AppDelegate
// Add this method to handle incoming Universal Links
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL else {
            return false
    }
    let handlers : [UniversalLinkHandler] = [AuthResponseHandler(), ErrorResponseHandler()]
    var validatedResponse : ValidatedResponse?
    for handler in handlers {
        if handler.canHandle(incomingURL: incomingURL) {
            validatedResponse = handler.getValidatedResponse()
            let initialViewController = UIStoryboard(name: "Main", bundle: nil).instantiateViewController(withIdentifier: "linkingStatusScreen") as! LinkingStatusViewController
            initialViewController.response = validatedResponse
            self.window?.rootViewController = initialViewController
            self.window?.makeKeyAndVisible()
            return true
        }
    }
    return false
}

// Incoming Universal Links handler protocol
protocol UniversalLinkHandler {

    //Validate the incoming URL scheme
    func canHandle(incomingURL:URL)-> Bool
    
    //Get the validated response
    func getValidatedResponse() -> ValidatedResponse?
}

extension UniversalLinkHandler {
    func validateState(state:String)->Bool {
        return StateHelper.validateState(state: state)
    }
}

// Successfully receiving the Amazon Authorization code
class AuthResponseHandler : UniversalLinkHandler {

    private let AUTH_RESPONSE_PARAMETERS: Set = ["code", "state", "scope"]
    private var validatedResponse: ValidatedResponse?
    
    func canHandle(incomingURL: URL) -> Bool {
    
        guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
            let queryParameters = components.queryItems else {
                return false
        }
        
        var validatedParameters : [String: String] = [:]
        for queryParameter in queryParameters {
            //duplicated parameters in URL
            if validatedParameters.keys.contains(queryParameter.name) {
                return false
            }
            //Unrecognized parameters in URL
            if !AUTH_RESPONSE_PARAMETERS.contains(queryParameter.name) {
                return false
            }
            validatedParameters[queryParameter.name] = queryParameter.value
        }
        
        guard let code = validatedParameters["code"], let state = validatedParameters["state"] else {
            return false
        }
        
        //validated the state
        if !validateState(state: state) {
            self.validatedResponse = ErrorResponse(url: incomingURL,error: "Invalid state", errorDescription: "The request has invalid state")
            return true
        }
        
        self.validatedResponse = AuthResponse(url: incomingURL,code: code, state: state, scope: validatedParameters["scope"])
        return true
    }
    
    func getValidatedResponse() -> ValidatedResponse? {
        return validatedResponse
    }
}

// Error authorization response handler
class ErrorResponseHandler : UniversalLinkHandler {
    private let ERROR_RESPONSE_PARAMETERS: Set = ["error", "error_description", "state"]
    private var validatedResponse: ValidatedResponse?
    
    func canHandle(incomingURL: URL) -> Bool {
        guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
            let queryParameters = components.queryItems else {
                return false
        }
        
        // Validate all query parameters 
        var validatedParameters : [String: String] = [:]
        for queryParameter in queryParameters {
            // Duplicated parameters in URL
            if validatedParameters.keys.contains(queryParameter.name) {
                return false
            }
            // Unrecognized parameters in URL
            if !ERROR_RESPONSE_PARAMETERS.contains(queryParameter.name) {
                return false
            }
            validatedParameters[queryParameter.name] = queryParameter.value
        }
        
        guard let error = validatedParameters["error"], let errorDescription = validatedParameters["error_description"], let state = validatedParameters["state"] else {
            return false
        }
        
        // validate the state
        if !validateState(state: state) {
            self.validatedResponse = ErrorResponse(url: incomingURL,error: "Invalid state", errorDescription: "The request has invalid state")
            return true
        }
        
        self.validatedResponse = ErrorResponse(url: incomingURL, error: error, errorDescription: errorDescription)
        return true
    }
    
    func getValidatedResponse() -> ValidatedResponse? {
        return validatedResponse
    }
}

// Validated response
class ValidatedResponse {

    // Universal Link URL that launched the App
    private(set) var url: URL
    init (url: URL) {
        self.url = url
    }
}

// Amazon authorization code response per the OAuth2 specification 
class AuthResponse : ValidatedResponse{
    private(set) var code : String
    private(set) var state: String
    
    //scope will be returned in Login with Amazon, will not be present in Alexa Companion flow
    private(set) var scope: String?
    init(url:URL, code:String, state:String, scope: String?) {
        self.code = code
        self.state = state
        self.scope = scope
        super.init(url:url)
    }
}

// Error response per the OAuth2 specification 
class ErrorResponse : ValidatedResponse {
    private(set) var error : String
    private(set) var errorDescription: String
    init(url: URL, error:String, errorDescription:String) {
        self.error = error
        self.errorDescription = errorDescription
        super.init(url: url)
    }
}

Make a request to your backend service to get both the Alexa app URL and the LWA fallback URL. You can implement this request in any way that you prefer, such as using RetroFit or any other Android library. The following code is a simple example.

fun doAppToApp(){
  val appToAppUrls: AppToAppUrls = yourBackendService.getAppToAppUrls();
    
  // This function is shown in a different example 
  openAlexaAppToAppUrl(appToAppUrls.alexaAppUrl, appToAppUrls.lwaFallBackUrl)
}

data class AppToAppUrls(
  @SerializedName("alexaAppUrl")
  val alexaAppUrl: String,

  @SerializedName("lwaFallBackUrl")
  val lwaFallBackUrl : String
)

interface BackendService {
  fun getAppToAppUrls() : AppToAppUrls
}

In this example, the app opens the Alexa app URL or, if the Alexa app is not installed, the LWA fallback URL.

Note the following:

• This example uses the PackageManager to verify that the Alexa app is installed and to verify that the installed version of the Alexa app can handle app-to-app account linking.
• If the Alexa app isn't installed or can't handle app-to-app account linking, your app must get the Amazon authorization code by using the LWA flow. For the LWA fallback URL format, see URLs and endpoints.
• This example opens the URLs by using the Android ACTION_VIEW intent. The app-to-app URL will open in the Alexa app and the LWA fallback URL will open in the user's default browser.

private fun openAlexaAppToAppUrl(alexaAppUrl: String, lwaFallbackUrl: String){

    if (AlexaAppUtil.isAlexaAppSupportAppLink(fragmentContext!!)) {
        val alexaAppToAppIntent = getAppToAppIntent(alexaAppUrl);
        startActivity(alexaAppToAppIntent)
    } else {
        val lwaAppToAppIntent = getAppToAppIntent(lwaFallbackUrl);
        startActivity(lwaAppToAppIntent)
    }
}

private fun getAppToAppIntent(appToAppUrl: String): Intent {
    return Intent(Intent.ACTION_VIEW, Uri.parse(appToAppUrl))
}
/**
 * Utility to check if the Alexa app is installed and supports app-to-app.
 */
object AlexaAppUtil {
    
    private const val ALEXA_PACKAGE_NAME = "com.amazon.dee.app"
    private const val ALEXA_APP_TARGET_ACTIVITY_NAME = "com.amazon.dee.app.ui.main.MainActivity"
    
    private const val REQUIRED_MINIMUM_VERSION_CODE = 866607211 

    /**
     * Check if the Alexa app is installed and supports App Links.
     *
     * @param context Application context.
     */
    @JvmStatic
    fun doesAlexaAppSupportAppToApp(context: Context): Boolean {
        try {
            val packageManager: PackageManager = context.packageManager
            val packageInfo = packageManager.getPackageInfo(ALEXA_PACKAGE_NAME, 0)

            return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
                packageInfo.longVersionCode > REQUIRED_MINIMUM_VERSION_CODE
            } else {
                packageInfo != null
            }

        } catch (e: PackageManager.NameNotFoundException) {
            // The Alexa App is not installed
            return false
        }
    }
}

In this example, the app validates and extracts the parameters from the call that the Alexa app made to its App Link.

/**
 * App-to-app result page landing activity.
 */
class AppToAppResultPageActivity : AppCompatActivity() {
  private lateinit var statusText: TextView
  private lateinit var goBackButton: Button

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val appLinkData = intent.data

    setContentView(R.layout.app_to_app_result)
    initializeComponents()
    statusText.text = "Linking your account"

    // Send the data returned from the Alexa App / LWA to your backend
    // to call the Skill Enablement API to link the accounts
    val accountLinking = linkAccountInBackend(appLinkData)

    displayAccountLinkingStatus(result);
  }

  private fun initializeComponents() {
    statusText = findViewById(R.id.text_status)
    goBackButton = findViewById(R.id.btn_goback)
    goBackButton.setOnClickListener {
      val intent = Intent(this, MainActivity::class.java)
      startActivity(intent)
    }
  }
}