SDK Android
Abrova Auth برای Android (ir.abrova:abrova-auth، Kotlin). ورود ناشناس، Google (Credential Manager)، Apple، ایمیل و رمز عبور، لینک یکبارمصرف و تلگرام با coroutineها؛ refresh token با کلیدی از Android Keystore رمزگذاری میشود؛ token provider برای همهی SDKهای ابرووا.
فقط از کلید API عمومی استفاده میکند. قرار دادنش در اپ امن است
همهی فراخوانیها تابع suspend هستند
refresh token با کلیدی رمزگذاری میشود که هرگز از Android Keystore خارج نمیشود
providerهای suspend، strict و blocking برای SDKهای دیگر ابرووا
authState برای Compose و coroutineها، یا یک listener کلاسیک
linkApple، linkGoogle و linkPassword شناسهی کاربر را حفظ میکنند
این صفحه 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 اضافه کنید:
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
}
}سپس وابستگی را در build.gradle.kts اپ اضافه کنید:
dependencies {
implementation("ir.abrova:abrova-auth:0.1.1")
}در کنسول ابرووا، Abrova Auth را برای پروژه (تنظیمات › محصولات) و روشهای ورود دلخواه را (Abrova Auth › روشهای ورود) روشن کنید.
مقداردهی اولیه#
SDK را یک بار، در Application.onCreate، با کلید API عمومی (ab_live_...) پیکربندی کنید. نشستی که در اجرای قبلی ذخیره شده بازیابی میشود.
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 { ... }).
ورود#
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های دیگر ابرووا#
AbrovaTrace.setUserId(auth.currentUserId) به ابرووا تریس وصل کنید.// 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 | نوع | وقتی کسی وارد نشده |
|---|---|---|
| tokenProvider | suspend () -> String? | null برمیگرداند |
| strictTokenProvider | suspend () -> 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 را به اپ اضافه کنید:
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 برمیگرداند بفرستید:
auth.signInWithApple(idToken, rawNonce, authorizationCode = code)
ایمیل و رمز عبور
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")
لینک یکبارمصرف
auth.sendMagicLink(email, redirectUrl = "myapp://auth/magic")
// In the activity the link opens:
AbrovaAuth.tokenFromLink(intent.dataString ?: "")?.let { auth.signInWithMagicLink(it) }تلگرام
val code = auth.requestTelegramCode("+989121234567")
if (!code.sent) startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(code.botUrl)))
auth.verifyTelegramCode("+989121234567", "123456")ارتقای کاربر ناشناس#
وصل کردن شناسهی کاربر را حفظ میکند، پس هر چه ساخته مال خودش میماند:
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.
}
}کاربر فعلی#
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خروج و حذف حساب#
auth.signOut() // this device; never fails auth.signOutEverywhere() // every device auth.deleteAccount() // deletes the user, then signs out
برای اینکه حذف چه چیزهایی را پاک میکند، امنیت و دادهها را ببینید.
مدیریت خطاها#
همهی خطاها از نوع AbrovaAuthException هستند. بر اساس code تصمیم بگیرید:
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 صدا نزنید.