ابرووا
شروع رایگان
☰ فهرست مستندات · SDK اندروید

SDK Android

Abrova Auth برای Android (ir.abrova:abrova-auth، Kotlin). ورود ناشناس، Google (Credential Manager)، Apple، ایمیل و رمز عبور، لینک یک‌بارمصرف و تلگرام با coroutineها؛ refresh token با کلیدی از Android Keystore رمزگذاری می‌شود؛ token provider برای همه‌ی SDKهای ابرووا.

Android 0.1.1Android API 23+به‌روزرسانی: ۵ آبان ۱۴۰۵
امن برای کلاینت

فقط از کلید API عمومی استفاده می‌کند. قرار دادنش در اپ امن است

Coroutineها

همه‌ی فراخوانی‌ها تابع suspend هستند

Keystore

refresh token با کلیدی رمزگذاری می‌شود که هرگز از Android Keystore خارج نمی‌شود

token providerها

providerهای suspend، strict و blocking برای SDKهای دیگر ابرووا

StateFlow

authState برای Compose و coroutineها، یا یک listener کلاسیک

ارتقای مهمان‌ها

linkApple، linkGoogle و linkPassword شناسه‌ی کاربر را حفظ می‌کنند

SDK Android برای Abrova Auth نسخه‌ی v0.1.1.

این صفحه ir.abrova:abrova-auth نسخه‌ی 0.1.1 را توضیح می‌دهد.

پیش‌نیازها.

Android API 23 (Android 6.0) یا بالاتر. Kotlin coroutines.

از دستیار هوش مصنوعی استفاده می‌کنید؟ این صفحه را با Copy page for AI به آن بدهید، یا همه‌ی مستندات را به‌صورت متن ساده از /docs/llms.txt بگیرید. دستیارهای هوش مصنوعی را ببینید.

نصب#

SDK از Abrova Center می‌آید. اول مخزن Maven ابرووا را در settings.gradle.kts اضافه کنید:

settings.gradle.ktsKotlin
dependencyResolutionManagement {
  repositories {
      google()
      mavenCentral()
      maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
  }
}

سپس وابستگی را در build.gradle.kts اپ اضافه کنید:

kotlin
dependencies {
    implementation("ir.abrova:abrova-auth:0.1.1")
}

در کنسول ابرووا، Abrova Auth را برای پروژه (تنظیمات › محصولات) و روش‌های ورود دلخواه را (Abrova Auth › روش‌های ورود) روشن کنید.

مقداردهی اولیه#

SDK را یک بار، در Application.onCreate، با کلید API عمومی (ab_live_...) پیکربندی کنید. نشستی که در اجرای قبلی ذخیره شده بازیابی می‌شود.

kotlin
import ir.abrova.auth.AbrovaAuth

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AbrovaAuth.shared.configure(this, "ab_live_your_api_key")
    }
}

همه‌ی فراخوانی‌های ورود تابع suspend هستند: آن‌ها را از داخل یک coroutine صدا بزنید (مثلاً lifecycleScope.launch { ... }).

ورود#

kotlin
val auth = AbrovaAuth.shared

val methods = auth.getMethods()
if (auth.currentUserId == null && methods.isEnabled("anonymous")) {
    auth.signInAnonymously()
}
Log.d("Auth", auth.currentUserId!!) // ru_...

فقط دکمه‌های روش‌هایی را نشان دهید که methods.isEnabled(...) برایشان true است: anonymous، apple، google، password، magicLink، telegram.

استفاده از کاربر با SDKهای دیگر ابرووا#

به‌زودی. Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. فراخوانی‌های زیر نشان می‌دهند کاربر Auth را چطور خواهند گرفت؛ امروز کاربر را با AbrovaTrace.setUserId(auth.currentUserId) به ابرووا تریس وصل کنید.
kotlin
// Abrova Sync: its provider is called off the main thread
AbrovaSyncConfig.builder(apiKey).userTokenProvider(auth.blockingTokenProvider).build()

// Abrova Push
AbrovaPushConfig(apiKey = apiKey, tokenProvider = auth.tokenProvider)

// Abrova Chat: create the client after sign-in
AbrovaChatConfig(apiKey = apiKey, userId = auth.currentUserId!!, tokenProvider = auth.strictTokenProvider)
Providerنوعوقتی کسی وارد نشده
tokenProvidersuspend () -> String?null برمی‌گرداند
strictTokenProvidersuspend () -> Stringخطای NOT_SIGNED_IN می‌دهد
blockingTokenProvider() -> String?null برمی‌گرداند. thread فراخواننده را block می‌کند: هرگز آن را روی main thread صدا نزنید

همه توکنی برمی‌گردانند که پیش از انقضا تمدید شده است. بعد از ورود یا خروج، متد refresh آن SDK را صدا بزنید (مثلاً sync.userTokens.refresh()). Abrova A/B Testing و موارد دیگر: استفاده با محصولات دیگر ابرووا.

روش‌های ورود#

هر روش صفحه‌ی خودش را با راه‌اندازی کنسول دارد: ناشناس، Apple، Google، ایمیل و رمز عبور، لینک یک‌بارمصرف، تلگرام.

ورود با Google

از Credential Manager با client ID وب خودتان و یک nonce هش‌شده استفاده کنید. androidx.credentials:credentials، androidx.credentials:credentials-play-services-auth و com.google.android.libraries.identity.googleid:googleid را به اپ اضافه کنید:

kotlin
val rawNonce = AbrovaNonce.generate()
val option = GetGoogleIdOption.Builder()
    .setServerClientId(WEB_CLIENT_ID)
    .setFilterByAuthorizedAccounts(false)
    .setNonce(AbrovaNonce.sha256(rawNonce))
    .build()
val response = CredentialManager.create(context)
    .getCredential(context, GetCredentialRequest.Builder().addCredentialOption(option).build())
val idToken = GoogleIdTokenCredential.createFrom(response.credential.data).idToken

auth.signInWithGoogle(idToken, rawNonce)

client ID وب را در Abrova Auth › روش‌های ورود › Google اضافه کنید.

ورود با Google به اتصال به Google، و در Android به Google Play services هم، نیاز دارد؛ بعضی کاربران در ایران هیچ‌کدام را ندارند. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام بدون Google کار می‌کنند، پس دست‌کم یکی از آن‌ها را هم ارائه کنید. ورود با Google را ببینید.

ورود با Apple

ورود وب Apple را با Services ID خودتان و AbrovaNonce.sha256(rawNonce) به‌عنوان nonce اجرا کنید، سپس id_token و code را که Apple برمی‌گرداند بفرستید:

kotlin
auth.signInWithApple(idToken, rawNonce, authorizationCode = code)

ایمیل و رمز عبور

kotlin
val result = auth.signUp(email, password, redirectUrl = "https://example.com/auth/verify")
// result.signedIn is false when the project requires a verified e-mail first.

auth.signIn(email, password)

auth.sendPasswordReset(email, redirectUrl = "https://example.com/auth/reset")
auth.resetPassword(token, newPassword) // ends every session; does not sign in
auth.verifyEmail(token)
auth.sendEmailVerification(redirectUrl = "https://example.com/auth/verify")

لینک یک‌بارمصرف

kotlin
auth.sendMagicLink(email, redirectUrl = "myapp://auth/magic")
// In the activity the link opens:
AbrovaAuth.tokenFromLink(intent.dataString ?: "")?.let { auth.signInWithMagicLink(it) }

تلگرام

kotlin
val code = auth.requestTelegramCode("+989121234567")
if (!code.sent) startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(code.botUrl)))
auth.verifyTelegramCode("+989121234567", "123456")

ارتقای کاربر ناشناس#

وصل کردن شناسه‌ی کاربر را حفظ می‌کند، پس هر چه ساخته مال خودش می‌ماند:

kotlin
try {
    auth.linkGoogle(idToken, rawNonce)   // or linkApple(...), linkPassword(email, password)
} catch (e: AbrovaAuthException) {
    if (e.code == AbrovaAuthErrorCode.PROVIDER_ALREADY_LINKED) {
        // This Google account already belongs to another user.
    }
}

کاربر فعلی#

kotlin
auth.currentUserId                 // null when signed out
auth.isSignedIn
val user = auth.me()               // AbrovaUser: id, isAnonymous, emailVerified, createdAt, providers
auth.currentUser                   // the profile last loaded by me()

// StateFlow of the user id
lifecycleScope.launch { auth.authState.collect { userId -> /* sign-in, sign-out, session end */ } }

// Or a listener
val registration = auth.addAuthStateListener { userId -> }
registration.remove()

val token = auth.getAccessToken()  // if you call your own API with it

خروج و حذف حساب#

kotlin
auth.signOut()            // this device; never fails
auth.signOutEverywhere()  // every device
auth.deleteAccount()      // deletes the user, then signs out

برای اینکه حذف چه چیزهایی را پاک می‌کند، امنیت و داده‌ها را ببینید.

مدیریت خطاها#

همه‌ی خطاها از نوع AbrovaAuthException هستند. بر اساس code تصمیم بگیرید:

kotlin
try {
    auth.signIn(email, password)
} catch (e: AbrovaAuthException) {
    when (e.code) {
        AbrovaAuthErrorCode.INVALID_CREDENTIALS -> showError("Wrong e-mail or password")
        AbrovaAuthErrorCode.RATE_LIMITED -> showError("Try again in ${e.retryAfterSec ?: 60} s")
        AbrovaAuthErrorCode.NETWORK_ERROR -> showError("No connection")
        else -> showError("Sign-in failed")
    }
}

message یک راهنمای انگلیسی برای توسعه‌دهنده است. SDK علاوه بر کدهای سرور از NETWORK_ERROR، NOT_SIGNED_IN و SDK_NOT_CONFIGURED (اول configure را صدا بزنید) استفاده می‌کند. خطای شبکه هرگز کاربر را خارج نمی‌کند. همه‌ی کدها: کدهای خطا.

عیب‌یابی#

SDK_NOT_CONFIGURED

AbrovaAuth.shared.configure(context, apiKey) را در Application.onCreate صدا بزنید.

ورود با Google با INVALID_ID_TOKEN شکست می‌خورد

Credential Manager، ID token را برای client ID وبی صادر می‌کند که به‌عنوان serverClientId می‌دهید. همان client ID وب را در کنسول اضافه کنید و AbrovaNonce.sha256(rawNonce) را به‌عنوان nonce بدهید.

اپ وقتی Sync توکن می‌خواهد قفل می‌شود

blockingTokenProvider thread خودش را block می‌کند. آن را فقط به SDKهایی بدهید که بیرون از main thread صدایش می‌زنند، و هرگز خودتان آن را روی main thread صدا نزنید.

این صفحه مفید بود؟
گزارش مشکل