Choose your integration path
Do not use the legacy shernova package
The pub.dev package shernova (1.x) is deprecated. Always add shernova_core (^2.0.0). shernova_ui is optional for ready-made screens. If your pubspec.yaml still lists shernova:, remove it: dart pub remove shernova && dart pub add shernova_core:^2.0.0.
Core vs optional UI
shernova_core is required for every Flutter app. shernova_ui is optional — use it for ready-made verifyPhone() screens, or build your own UI with the headless API.
| Package | Version | Role |
|---|---|---|
| shernova_core | 2.0.1 | Required — headless SDK (init, verify, watch, receipt) |
| shernova_ui | 2.3.1 | Optional — verifyPhone() with trust UI + afterVerified hook |
| shernova_cli | 2.0.0 | dart run shernova_cli setup (--with-ui for optional UI) |
Installation — Path A (headless, recommended)
dart pub add shernova_core:^2.0.0
dart pub add --dev shernova_cli:^2.0.0
dart run shernova_cli setup --pk pk_test_YOUR_KEY --app-id YOUR_APP_UUIDInstallation — Path B (optional UI)
dart pub add shernova_core:^2.0.0 shernova_ui:^2.0.0
dart pub add --dev shernova_cli:^2.0.0
dart run shernova_cli setup --pk pk_test_YOUR_KEY --app-id YOUR_APP_UUID --with-uiYou can also add UI later: dart pub add shernova_ui:^2.0.0 (no app store update needed for server-side string changes).
Initialization
import 'package:shernova_core/shernova_core.dart';
import 'shernova_config.dart';
await Shernova.init(shernovaConfig);ShernovaConfig
| Field | Required | Description |
|---|---|---|
| appId | Yes | Application UUID from dashboard |
| publishableKey | Yes | pk_test_… (test keys) or pk_live_… (live keys) |
| apiBaseUrl | Yes | https://api.shernova.com |
| packageName | Yes (Android) | Android applicationId |
| sha256 | Yes (Android) | Signing certificate SHA256 (64 hex, lowercase) |
| bundleId | Yes (iOS) | iOS bundle identifier from Xcode |
| teamId | Yes (iOS) | Apple Developer Team ID |
Headless flow (shernova_core only — recommended)
final session = await Shernova.verify(phoneNumber: '+201012345678');
await for (final update in Shernova.watch(session.sessionId)) {
if (update.status == 'verified') {
final receipt = await Shernova.getReceipt(session.sessionId);
break;
}
}Optional UI flow (shernova_ui)
import 'package:shernova_core/shernova_core.dart';
import 'package:shernova_ui/shernova_ui.dart';
import 'shernova_config.dart';
await Shernova.init(shernovaConfig);
final session = await verifyPhone(
context: context,
phoneNumber: '+201012345678',
);Server-driven branding (ui_theme)
From shernova_core 2.0.1+ / shernova_ui 2.3.0+, POST /v1/sdk/token returns ui_theme (logo_url, logo_size_dp, footer_font_size_sp). The verification footer reads these values on each session — update logo or sizes on Shernova without republishing client apps.
Android auto-return
From shernova_ui 2.2.0+, verifyPhone() polls call state from a foreground service and restores the app automatically on MIUI/Xiaomi (grant Phone, Notifications, and Call phone when prompted). Use afterVerified to run registration while a progress overlay stays visible:
final session = await verifyPhone(
context: context,
phoneNumber: '+201012345678',
afterVerified: (session) async {
await myBackend.completeSignup(receipt: await Shernova.getReceipt(session.sessionId));
},
);Publishing to Google Play requires foreground-service and phone permission declarations when using shernova_ui. See Publish to Google Play for ready-made declaration text and review tips.
iOS verification
On iOS, the same Flutter packages work without native auto-return — users return manually after the call. See iOS verification & App Store.
Shernova static API
| Method | Description |
|---|---|
| Shernova.init(config) | Exchange pk_* for SDK JWT via POST /v1/sdk/token |
| Shernova.verify({phoneNumber}) | POST /v1/verifications |
| Shernova.watch(sessionId) | Poll GET /v1/verifications/:id |
| Shernova.getReceipt(sessionId) | POST /v1/verifications/:id/receipt |
| Shernova.cancel(sessionId) | DELETE /v1/verifications/:id |
Test keys (pk_test_ / sk_test_)
Use pk_test_ / sk_test_ in development builds. Test sessions use real Android gateways and consume credits — call the gateway_phone_number from the same phone the user entered. Use pk_live_ for production users.
Errors
SDK throws ShernovaError with error, errorCode (SH_xxx), and message. Common: signature_not_registered (SH_008), insufficient_credits (SH_010). See Error codes.