Виджет 3 в 1 для Android

Документация актуальна для версии VK ID SDK — 2.6.0.

VK ID предлагает авторизацию сразу через несколько OAuth в виджете 3 в 1. Можно подключить сразу три способа авторизации для удобства пользователей: через аккаунт ВКонтакте, Одноклассники и Mail. Если вы не хотите использовать все три способа авторизации, можно подключить только авторизацию через определенные аккаунты социальных сетей, например, через аккаунты ВКонтакте и Одноклассников — выбор делаете вы. В зависимости от подключенных способов входа на экран авторизации вашего сервиса добавляются соответствующие кнопки с иконками. Когда пользователь пройдет авторизацию в вашем сервисе удобным способом, у вас будет Access token. В качестве альтернативы виджету 3 в 1 вы можете подключить дополнительные OAuth вместе с One Tap кнопкой или внутри шторки.

При первой авторизации пользователя через Одноклассники или Mail его аккаунт привязывается к аккаунту VK ID, и пользователю понадобится авторизоваться в нём. При следующих попытках входа пользователю будет достаточно ввести только второй фактор от аккаунта VK ID.

Чтобы использовать авторизацию через виджет 3 в 1 в приложении на Android:

Убедитесь, что в подразделе Авторизация приложения указаны нужные дополнительные способы входа в ваш сервис: Авторизация через Одноклассники, Авторизация через Mail.
Выберите способ подключения OAuth: с помощью Compose или XML. Дальнейшая работа с кнопкой определяется вашим подходом к работе с UI.

Конфигурация виджета с иконками авторизации

Подключения OAuth через Compose

OAuthListWidget — конфигурация виджета с кнопками-иконками авторизации. Имеет следующие параметры: Конфигурация с помощью Compose

Поле	Описание
oAuths	Список доступных способов входа
style	Стилизация виджета авторизации
onAuthCode	Callback-метод, который вызывается при успешной аутентификации. В callback передается авторизационный код, который нужен для обмена на токены
onAuth	Callback-метод, который вызывается при успешной авторизации
onFail	Callback-метод, который вызывается при неуспешной авторизации
authParams	Параметр, через который в конфигурацию OAuthListWidget передаются доступы. Используется для получения данных пользователя

Чтобы использовать OAuthListWidget на своих экранах в приложении на Android, выполните инструкции ниже.

Укажите зависимости

Добавьте библиотеку для работы с виджетом OAuth в модули, где она будет использоваться. build.gradle.kts

dependencies {
    implementation("com.vk.id:multibranding-compose:${sdkVersion— указывается последняя версия SDK, смотрите номер версии в начале страницы}")
}

Разместите виджет в вёрстке — так вы сможете добавить его на экран. ScreenWithMultibranding.kt

@Composable
fun ScreenWithMultibranding() {
    OAuthListWidget(
        onAuth = { /*...*/ }
    )
}

При необходимости настройте поведение виджета OAuth с помощью параметра oAuths. Он позволяет указать способы входа, которые будут использоваться в виджете OAuth, если вы не хотите использовать все три: ScreenWithMultibranding.kt

OAuthListWidget(
    oAuths = setOf(OAuth.VK, OAuth.MAIL)
)

Обратите внимание, что хотя бы один из способов входа нужно указать обязательно.

Стилизация виджета авторизации

Для настройки отображения виджета OAuth используйте параметр style. Стилизация виджета задаётся с помощью класса OAuthListWidgetStyle. Возможные значения:

Название класса	Описание
OAuthListWidgetStyle	Класс, который определяет стиль виджета. Возможные значения: Light() — светлая тема; Dark() — тёмная тема.

Радиус скругления виджета задаётся с помощью параметра cornersStyle. Возможные значения:

None — квадратная кнопка, скругление отсутствует;
Rounded — полукруглая кнопка;
Round — круглая кнопка;
Default — скругление кнопки по умолчанию, используется значение Rounded;
Custom — пользовательское значение радиуса скругления, указанное в dp.

Параметр sizeStyle в зависимости от префикса (SMALL/MEDIUM/LARGE) определяет размер текста, а суффикс обозначает высоту виджета OAuth в dp. Значение по умолчанию — DEFAULT, которое совпадает с MEDIUM_44.

Другие возможные значения

SMALL_32;
SMALL_34;
SMALL_36;
SMALL_38;
MEDIUM_40;
MEDIUM_42;
MEDIUM_44;
MEDIUM_46;
LARGE_48;
LARGE_50;
LARGE_52;
LARGE_54;
LARGE_56.

ScreenWithMultibranding.kt

@Composable
fun ScreenWithMultibranding() {
    OAuthListWidget(
        style = OAuthListWidgetStyle.Light(
            cornersStyle = OAuthListWidgetCornersStyle.Custom(2f),
            sizeStyle = OAuthListWidgetSizeStyle.SMALL_32,
        )
    )
}

Как получить токен

Когда пользователь пройдет авторизацию, в ответ VK ID SDK передаст информацию о способе авторизации и Access token, который позволяет работать с API ВКонтакте и получать информацию о пользователе, или ошибку. Обработка успешной авторизации Если авторизация успешна, с Access token можно получить необходимую информацию о пользователе, используя запросы в api.vk.ru, — интеграция завершена. ScreenWithMultibranding.kt

@Composable
fun ScreenWithMultibranding() {
    OAuthListWidget(onAuth = { oAuth, token ->
        // Использование токена и OAuth.
    })
}

Также после получения Access token происходит его привязка к IP-адресу:

если вы используете авторизацию через SDK с обменом кода на фронтенде, Access token привязывается к IP-адресу пользователя. Этот токен можно использовать только с того клиентского устройства, на котором прошла авторизация;
если вы используете авторизацию через SDK с обменом кода на бэкенде, Access token привязывается к IP-адресу бэкенда сервиса. Токен можно использовать только на одном бэкенд-сервере — на том, который получил этот токен. Если передать токен на другой бэкенд-сервер или на фронтенд, возникнет ошибка.

Обработка ошибок Если авторизация пользователя завершается с ошибкой, ее можно обработать и отобразить пользователю. Так он поймет, что пошло не так и почему авторизация не выполнилась. В результате ошибки авторизации в коде вы получите callback, в котором можно обработать ошибку. ScreenWithMultibranding.kt

@Composable
fun ScreenWithMultibranding() {
  OAuthListWidget(onFail = { oAuth, fail ->
        when (fail) {
            is VKIDAuthFail.Canceled -> TODO()
            is VKIDAuthFail.FailedApiCall -> TODO()
            is VKIDAuthFail.FailedOAuth -> TODO()
            is VKIDAuthFail.FailedOAuthState -> TODO()
            is VKIDAuthFail.FailedRedirectActivity -> TODO()
            is VKIDAuthFail.NoBrowserAvailable -> TODO()
        }
    })
}

Подключения OAuth через XML

OAuthListWidget — конфигурация виджета, который содержит в себе кнопки с иконками авторизации через все доступные для VK ID сервисы. Имеет следующие параметры: Конфигурация с помощью XML

Поле	Описание
vkid_oAuthListOAuths	Список доступных способов входа
vkid_OAuthListStyle	Стилизация виджета авторизации
vkid_oAuthListScopes	Параметр, через который в конфигурацию OAuthListWidget передаются доступы. Используется для получения данных пользователя

Помимо инициализации с помощью атрибутов XML мы даем возможность настроить конфигурацию с помощью property: Конфигурация с помощью property

Поле	Описание
oAuths	Список доступных способов входа
style	Стилизация виджета авторизации
authParams	Параметр, через который в конфигурацию OAuthListWidget передаются доступы. Используется для получения данных пользователя

Также в OAuthListWidget есть callback-метод setCallbacks(), который вызывается в зависимости от переданных параметров:

onAuthCode — при успешной аутентификации. В callback передается авторизационный код, который нужен для обмена на токены. Подробнее;
onAuth — при успешной авторизации.
onFail — при неуспешной авторизации.

Чтобы использовать OAuthListWidget на своих экранах в приложении на Android, выполните инструкции ниже.

Укажите зависимости

Добавьте библиотеку для работы с виджетом OAuth в модули, где она будет использоваться. build.gradle.kts

dependencies {
    implementation("com.vk.id:multibranding-xml:${sdkVersion — указывается последняя версия SDK, смотрите номер версии в начале страницы}")
}

Разместите виджет в вёрстке — так вы сможете добавить его на экран. ScreenWithMutlibranding.kt

<com.vk.id.multibranding.xml.OAuthListWidget
    android:layout_width="300dp"
    android:layout_height="wrap_content"
    />

findViewById<OAuthListWidget>(R.id.oAuthListWidget).oAuths = setOf(OAuth.MAIL, OAuth.OK)

Обратите внимание, что хотя бы один из способов входа нужно указать обязательно.

Стилизация виджета авторизации

Настроить отображение виджета OAuth можно программно или через XML. Программно стиль настраивается аналогично Compose. ScreenWithMutlibranding.kt

fun onCreate(/* ... */) {
    findViewById<OAuthListWidget>(R.id.oAuthListWidget).style = OAuthListWidgetStyle.Light(
        cornersStyle = OAuthListWidgetCornersStyle.Custom(8f),
        sizeStyle = OAuthListWidgetSizeStyle.SMALL_36,
    )
}

Также параметры виджета OAuth можно указывать в XML. Чтобы задать стиль виджета, используйте параметр vkid_OAuthListStyle с одним из возможных значений:

Название	Описание
light	Светлая тема
dark	Тёмная тема
system	Системная тема, которая меняется между light и dark. Зависит от системных настроек оформления в телефоне — согласно указанным настройкам будет использоваться тема light или dark

В параметре vkid_oAuthListCornerRadius задаётся величина закругления виджета в dp. Параметр vkid_oAuthListSize в зависимости от префикса (small/medium/large) определяет размер текста, а суффикс обозначает высоту виджета OAuth в dp. Значение по умолчанию — standard, которое совпадает с medium44.

Другие возможные значения

standard;
small32;
small34;
small36;
small38;
medium40;
medium42;
medium44;
medium46;
large48;
large50;
large52;
large54;
large56.

Пример настройки стиля через XML см. ниже. ScreenWithMutlibranding.kt

<com.vk.id.multibranding.xml.OAuthListWidget
    android:layout_width="355dp"
    android:layout_height="wrap_content"
    app:vkid_OAuthListStyle="dark"
    app:vkid_oAuthListCornerRadius="8dp"
    app:vkid_oAuthListSize="small32" />

Как получить токен

Когда пользователь пройдет авторизацию, в ответ VK ID SDK передаст Access token, который позволяет работать с API ВКонтакте и получать информацию о пользователе, или ошибку. Обработка успешной авторизации Если авторизация успешна, с Access token можно получить необходимую информацию о пользователе, используя запросы в api.vk.ru, — интеграция завершена. ScreenWithMultibranding.kt

fun onCreate(/* ... */) {
    findViewById<OAuthListWidget>(R.id.oAuthListWidget).setCallbacks(
        onAuth = { oAuth, token -> /* Использование токена */ }
    )
}

Также после получения Access token происходит его привязка к IP-адресу:

если вы используете авторизацию через SDK с обменом кода на фронтенде, Access token привязывается к IP-адресу пользователя. Этот токен можно использовать только с того клиентского устройства, на котором прошла авторизация;
если вы используете авторизацию через SDK с обменом кода на бэкенде, Access token привязывается к IP-адресу бэкенда сервиса. Токен можно использовать только на одном бэкенд-сервере — на том, который получил этот токен. Если передать токен на другой бэкенд-сервер или на фронтенд, возникнет ошибка.

fun onCreate(/* ... */) {
    findViewById<OAuthListWidget>(R.id.oAuthListWidget).setCallbacks(
        onFail = { oAuth, fail ->
            when (fail) {
                is VKIDAuthFail.Canceled -> TODO()
                is VKIDAuthFail.FailedApiCall -> TODO()
                is VKIDAuthFail.FailedOAuth -> TODO()
                is VKIDAuthFail.FailedOAuthState -> TODO()
                is VKIDAuthFail.FailedRedirectActivity -> TODO()
                is VKIDAuthFail.NoBrowserAvailable -> TODO() }
        }
    )
}

Как получить и обработать данные

Если приложению нужно получить данные пользователя, оно сможет воспользоваться методом vkid.getUserData(). Этот метод использует сохраненный AT и сделает запрос к /user_info. Подробнее смотрите в этой статье. Обратите внимание, что для доступа к телефону и почте нужно передать scopes "phone" и "email" соответственно. Это можно сделать через класс OAuthListWidget, передав в параметре scopes нужные доступы:

Compose

XML в коде

XML в вёрстке

OAuthListWidget(
    ...
    authParams = VKIDAuthUIParams {
        scopes = setOf("phone", "email")
    }
)

Дальнейшие шаги

При использовании схемы авторизации через SDK с обменом кода на бэкенде сгенерируйте параметры PKCE на стороне вашего сервиса и затем настройте авторизацию.
Реализуйте получение информации о пользователе и другие необходимые методы.

Виджет 3 в 1 для Android

Подключения OAuth через Compose

Укажите зависимости

Добавьте виджет на экран

Стилизация виджета авторизации

Как получить токен

Подключения OAuth через XML

Укажите зависимости

Добавьте виджет на экран

Стилизация виджета авторизации

Как получить токен

Как получить и обработать данные

Дальнейшие шаги