https://github.com/vkcom/vkid-android-sdk
https://github.com/vkcom/vkid-android-sdk
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/vkcom/vkid-android-sdk
- Owner: VKCOM
- License: mit
- Created: 2023-09-25T13:31:08.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-01-29T14:31:04.000Z (over 1 year ago)
- Last Synced: 2025-01-29T18:45:46.555Z (over 1 year ago)
- Language: Kotlin
- Size: 8.75 MB
- Stars: 31
- Watchers: 9
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .gitlab/CODEOWNERS
Awesome Lists containing this project
README
VK ID SDK — библиотека для авторизации пользователей Android-приложений с помощью аккаунта VK ID.
---
:information_source: Версия VK ID SDK 2.0.0 поддерживает авторизацию по
протоколу [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-10), а также способы входа через аккаунты Одноклассников и Mail.
---
## Демонстрация
SDK поставляется с [тестовым примером приложения](sample/app), где можно посмотреть работу авторизации.
Чтобы тестовое приложение успешно собралось, сначала создайте файл `sample/app/secrets.properties` и пропишите в нем client_id и client_secret вашего
приложения VK ID:
Файл `secrets.properties`:
```
VKIDClientSecret=Ваш защищённый ключ
VKIDClientID=Ваш ID приложения
```
## Предварительно
Что такое VK ID и как интегрировать его в приложение
читайте [в статье "Начало работы"](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/connection/android/install).
Чтобы подключить VK ID SDK, сначала получите ID приложения (app_id) и защищенный ключ (client_secret). Для этого создайте приложение
в [кабинете подключения VK ID](https://id.vk.ru/business/go).
Документация API SDK доступна [на Github](https://vkcom.github.io/vkid-android-sdk/).
## Установка
Для начала работы добавьте репозитории:
```kotlin
pluginManagement {
repositories {
...
maven(url = "https://artifactory-external.vkpartner.ru/artifactory/vkid-sdk-android/")
maven(url = "https://artifactory-external.vkpartner.ru/artifactory/maven/")
}
}
dependencyResolutionManagement {
repositories {
...
maven {
url = URI("https://artifactory-external.vkpartner.ru/artifactory/vkid-sdk-android/")
}
maven {
url = URI("https://artifactory-external.vkpartner.ru/artifactory/maven/")
}
maven {
url = URI("https://artifactory-external.vkpartner.ru/artifactory/vk-id-captcha/android/")
}
}
}
```
Настройте плагин для плейсхолдеров:
```kotlin
// Корневой build.gradle.kts
// Подключение плагина для Manifest Placeholders.
plugins {
...
id("vkid.manifest.placeholders") version "1.1.0" apply true
}
// Добавление значений в Manifest Placeholders.
vkidManifestPlaceholders {
// Добавьте плейсхолдеры сокращенным способом. Например, vkidRedirectHost будет "vk.ru", а vkidRedirectScheme будет "vk$clientId".
init(
clientId = clientId,
clientSecret = clientSecret,
)
// Или укажите значения явно через properties, если не хотите использовать плейсхолдеры.
vkidRedirectHost = "vk.ru" // Обычно vk.ru.
vkidRedirectScheme = "vk1233445" // Строго в формате vk{ID приложения}.
vkidClientId = clientId
vkidClientSecret = clientSecret
}
```
```kotlin
// build.gradle.kts app модулей
plugins {
id("vkid.manifest.placeholders")
}
```
И подключите библиотеку:
```kotlin
implementation("com.vk.id:vkid:${sdkVersion}")
```
И пропишите плейсхолдеры манифеста в секции `android` в `build.gradle.kts`:
```kotlin
android {
//...
defaultConfig {
addManifestPlaceholders(
mapOf(
"VKIDClientID" to "1233445", // ID вашего приложения (app_id).
"VKIDClientSecret" to "000000000000", // Ваш защищенный ключ (client_secret).
"VKIDRedirectHost" to "vk.ru", // Обычно используется vk.ru.
"VKIDRedirectScheme" to "vk1233445", // Должно быть vk{ID приложения}.
)
)
}
}
```
## Интеграция
Инициализация VK ID SDK
Инициализируйте работу VK ID SDK через объект `VKID`.
```kotlin
// В Application
fun onCreate() {
super.onCreate()
VKID.init(this)
}
```
Авторизация
Результат авторизации передается в коллбэк `VKIDAuthCallback`, поэтому его нужно объявить:
```kotlin
private val vkAuthCallback = object : VKIDAuthCallback {
override fun onAuth(accessToken: AccessToken) {
val token = accessToken.token
//...
}
override fun onFail(fail: VKIDAuthFail) {
when (fail) {
is VKIDAuthFail.Canceled -> { /*...*/ }
else -> {
//...
}
}
}
}
```
Авторизация запускается с помощью метода authorize(), у которого есть два варианта вызова:
```kotlin
viewModelScope.launch {
VKID.instance.authorize(vkAuthCallback)
}
```
или с передачей LifecycleOwner:
```kotlin
VKID.instance.authorize(this@MainActivity, vkAuthCallback) // Первый параметр LifecycleOwner, например активити.
```
Параметры aвторизации
Вы можете передать дополнительные параметры авторизации с помощью вспомогаельной билдер-функции:
```kotlin
VKID.instance.authorize(
callback = vkAuthCallback,
params = VKIDAuthParams {
scopes = setOf("status", "email")
}
)
```
Обновление токена
Токен живет ограниченное количество времени, при получении ошибки от апи обновите его:
```kotlin
viewModelScope.launch {
VKID.instance.refreshToken(
callback = object : VKIDRefreshTokenCallback {
override fun onSuccess(token: AccessToken) {
// Использование token
}
override fun onFail(fail: VKIDRefreshTokenFail) {
when (fail) {
is FailedApiCall -> fail.description // Использование текста ошибки
is RefreshTokenExpired -> fail // Это означает, что нужно пройти авторизацию заново
is Unauthorized -> fail // Пользователь понимает, что сначала нужно авторизоваться
}
}
}
)
}
```
Также есть версия с передачей LifecycleOwner:
```kotlin
VKID.instance.refreshToken(
lifecycleOwner = MainActivity@ this,
callback = ... // такой же, как в suspend версии
)
```
## Документация
- [Что такое VK ID](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/intro/start-page)
- [Создание приложения](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/connection/create-application)
- [Требования к дизайну](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/connection/guidelines/design-rules-oauth)
- [Кнопка OneTap](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/connection/elements/onetap-button/onetap-android)
- [Шторка авторизации](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/connection/elements/onetap-drawer/floating-onetap-android)
- [Виджет 3в1](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/connection/elements/widget-3-1/three-in-one-android)
## Локальная сборка
Если проект не собирается со странными ошибками, то скореe всего нужно выставить в настройках проекта в студии **jdk-17**. Для того, чтобы работали
градл-скрипты из консоли, также нужно прописать в переменной среды JAVA_HOME путь по которому находится jdk **17-й** версии.
## Contributing
Проект VK ID SDK имеет открытый исходный код на GitHub, и вы можете присоединиться к его доработке — мы будем благодарны за внесение улучшений и
исправление возможных ошибок.
### Contributing Guide
В [руководстве](CONTRIBUTING.md) вы можете подробно ознакомиться с процессом разработки и узнать, как предлагать улучшения и исправления, а ещё — как
добавлять и тестировать свои изменения в VK ID SDK.
Также рекомендуем ознакомиться с общими [правилами оформления кода](CODE_STYLE.md) в проекте и [списком технических команд](TECHNICAL_COMMANDS.md).