---
metadata:
  - name: generator
    content: Diplodoc Platform v5.44.0
alternate:
  - https://yandex.com/dev/id/doc/en/mobileauthsdk/ios/2.1.1/sdk-ios-methods.md
  - https://yandex.com/dev/id/doc/ru/mobileauthsdk/ios/2.1.1/sdk-ios-methods.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/id/doc/en/llms.txt

# Method guide

## YandexLoginSDK class {#yandexloginsdk}

The main class involved in all interactions with the SDK. This class is a singleton. Its only instance is a [static variable `shared`](#yandexloginsdk-statvars).

To start authorization, use the [method `authorize(with:customValues:authorizationStrategy:)`](#yandexloginsdk-methods-authorizationstrategy). A parent View Controller has to be passed to it.

To get the authorization result, you need to register a SDK Yandex ID observer using the [`add(observer:)` method](#yandexloginsdk-methods-addobserver). When you no longer need notifications from LoginSDK, you can unregister the observer using the [`remove(observer:)` method](#yandexloginsdk-methods-removeobserver).

To delete the saved tokens or re-authorize the user, use the [`logout()` method](#yandexloginsdk-methods-removeobserver).

### **Static variables** {#yandexloginsdk-statvars}

* The only instance of the `YandexLoginSDK` class:

   ```swift
   static var shared: YandexLoginSDK { get }
   ```
   
   Make sure to use the static variable `shared` to get variable values and call methods.

* The current LoginSDK version:

   ```swift
   static var version: String { get }
   ```
   
   It's formatted in accordance with Semantic Versioning (SemVer).

### **Methods** {#yandexloginsdk-methods}

#### {#yandexloginsdk-methods-authorizationstrategy}

* Activate SDK Yandex ID:

   ```swift
   func activate(with: String, authorizationStrategy: AuthorizationStrategy) throws
   ```
   
   Pass the [Client ID](https://yandex.com/dev/id/doc/en/register-client.md#app-params) and your selected [authorization strategy `authorizationStrategy`](#authorizationstrategy) (`.default` is the default value) to this method. The method will validate your app configuration before the SDK is activated. If the validation fails, the method call will result in an error. 

* Obtain a token:

   ```swift
   func handleUserActivity(NSUserActivity) throws
   ```
   
   This method handles the [NSUserActivity](https://developer.apple.com/documentation/foundation/nsuseractivity/) argument to extract the URL passed to the app and then extract the tokens from the URL. If successful, the observers call the [`didFinishLogin(with:)` method](#loginsdkobserver-methods) with a `.success` argument and an associated value of the [LoginResult](#loginresult) type.


* Wrap the method `handleUserActivity(_:)`:

   ```swift
   func tryHandleUserActivity(NSUserActivity) –> Bool
   ```

   The method `handleUserActivity(_:)` may throw an error, while the method `tryHandleUserActivity(_:)` calls it in a ##do-catch## statement and returns `false`, if an error occurs.

* Obtain the authorization code:

   ```swift
   func handleOpenURL(URL) throws
   ```

   This method handles the URL passed to it to extract the authorization code and then uses that code to request tokens. If successful, the observers call the [`didFinishLogin(with:)`](#loginsdkobserver-methods) method with a `.success` argument and an associated value of the [LoginResult](#loginresult) type.

* Wrap the method `handleOpenURL(_:)`:

   ```swift
   func tryHandleOpenURL(URL) –> Bool
   ```

   The method `handleOpenURL(_:)` may throw an error, while the method `tryHandleOpenURL(_:)` calls it in a ##do-catch## statement and returns `false` if an error occurs.

* Validate the URL:

   ```swift
   func isURLRelatedToSDK(URL) –> Bool
   ```

   This method checks whether the URL passed to it is related to SDK Yandex ID.

#### {#yandexloginsdk-methods-addobserver}

* Add an observer:

   ```swift
   func add(observer: any LoginSDKObserver)
   ```

   This method adds the object passed to it to the list of SDK Yandex ID observers. The observer will receive notifications about all the results of the SDK running, specifically about successful authorizations and errors.

#### {#yandexloginsdk-methods-removeobserver}

* Remove an observer:

   ```swift
   func remove(observer: any LoginSDKObserver)
   ```

   This method removes the object passed to it from the list of SDK Yandex ID observers.

* Start the authorization process:

   ```swift
   func authorize(with: UIViewController, customValues: [String: String]?, authorizationStrategy: AuthorizationStrategy) throws
   ```

   The [`parentViewController`](https://developer.apple.com/documentation/uikit/uiviewcontroller/) parameter is required even when the selected [authorization strategy](#authorizationstrategy) is to use Yandex apps. The reason is that there may be no such apps on the user's device. In this case, the SDK will switch to authorization via a web interface. The `customValues` parameter has a default value of `nil`.

#### {#yandexloginsdk-methods-logout}

* Delete the tokens from storage:

   ```swift
   func logout() throws
   ```

   Use this method when there's a need to re-authorize.


## YandexLoginSDK.AuthorizationStrategy enumeration {#authorizationstrategy}

The enumeration (enum) that determines the user authorization strategy for SDK Yandex ID. Depending on the value of the `authorizationStrategy` property set in [YandexLoginSDK](#yandexloginsdk), SDK Yandex ID decides whether to authorize the user via Yandex apps or a web interface.

### Values {#authorizationstrategy-values}

* Default strategy:

   ```swift
   case default
   ```

   When this strategy is selected, SDK Yandex ID tries to open a Yandex app that supports authorization and authorize the user there. If there are no such apps, SDK Yandex ID tries to authorize the user via a web interface.

* The web authorization strategy:

   ```swift
   case webOnly
   ```

   If you need to authorize the user via a web interface, set this strategy when activating the app in the method [`activate(with:authorizationStrategy:)`](#yandexloginsdk-methods-authorizationstrategy) of the [YandexLoginSDK](#yandexloginsdk) class instance. In this case, the activator won't require the app's _Info.plist_ to have schemes for launching Yandex apps.


## LoginResult structure {#loginresult}

The `LoginResult` structure stores the tokens that were obtained during authorization. An instance of this structure is passed to SDK Yandex ID observers in the [method `didFinishLogin(with:)`](#loginsdkobserver-methods) when the authorization is successful.

### Variables {#loginresult-vars}

* OAuth token:

   ```swift
   var token: String { get }
   ```

   Used in requests to Yandex APIs.

* JSON Web Token:

   ```swift
   var jwt: String { get }
   ```

   Learn more about the [JSON Web Token](https://yandex.com/dev/id/doc/en/tokens/jwt.md).

* The structure represented as a dictionary:

   ```swift
   var asDictionary: [String: String] { get }
   ```

   The dictionary's keys and values are strings. The key for the OAuth token is *“token“*, and the key for the JSON Web Token is *“jwt“*.

* The structure represented as a string:

   ```swift
   var asString: String { get }
   ```


## LoginSDKObserver protocol {#loginsdkobserver}

SDK Yandex ID uses the `LoginSDKObserver` protocol to notify observers that the authorization process has ended. Only classes can implement this protocol.

To subscribe to changes, use the [`addObserver(_:)` method](#yandexloginsdk-methods-addobserver) of the YandexLoginSDK class.

To unsubscribe from changes, use the [` removeObserver(_:) ` method](#yandexloginsdk-methods-removeobserver) of the YandexLoginSDK class.

### Methods {#loginsdkobserver-methods}

* Finish authorization:

   ```swift
   func didFinishLogin(with: Result<LoginResult, any Error>)
   ```

   This method is called in two cases:
   * SDK Yandex ID has successfully completed the authorization, obtaining an OAuth token and a JSON Web Token.
   * SDK Yandex ID has encountered an error during the authorization.
   
   An unsuccessful authorization attempt will have an error as an associated value, with a type conforming to the `Error` protocol. Specifically, the error may correspond to the `YandexLoginSDKError` protocol.


## YandexLoginSDKError protocol {#yandexloginsdkerror}

The `YandexLoginSDKError` protocol combines all the errors generated by SDK Yandex ID. You can use the `message` variable to get a string description for any such error.

### Variables {#yandexloginsdkerror-vars}

* A string with detailed information about an error:

   ```swift
   var message: String { get }
   ```