Audit Events

The SDK emits analytics events via the onEvent callback in SsoAnalyticsConfig. Use these to track user behavior through the authentication flow.

Setup

await SsoSdk.initialize(SsoConfig(
  baseUrl: '...',
  origin: SsoOrigin.heroDev,
  appName: 'MyApp',
  analytics: SsoAnalyticsConfig(
    onEvent: (event) {
      // event.name — event name (String)
      // event.properties — event data (Map<String, dynamic>)
      // event.timestamp — when the event occurred (DateTime)
      print('${event.name}: ${event.properties}');
    },
    onError: (error) {
      print('Error: ${error.code} ${error.message}');
    },
  ),
));

Event reference

User actions

Event name	When it fires	Data
login_click	User taps "Log in" button on the login page	—
signup_click	User taps "Sign Up" / "Next" on the registration page	—
provider_click	User taps a social/wallet provider button	{ provider: 'google' | 'apple' | 'x' | 'telegram' | 'wallet' }

Auth results

Event name	When it fires	Data
success_login	Login completes successfully (tokens received)	—
success_signup	Registration request sent successfully	—
invalid_credentials	Login fails due to wrong email/password	—

Verification flow

Event name	When it fires	Data
left_email_verification_page	User leaves the email verification page	{ email, user_id }
left_phone_verification_page	User leaves the phone verification page	{ phone, user_id }

Backup flow

Event name	When it fires	Data
skipped_backup_email	User skips adding a backup email	{ user_id }
skipped_backup_phone	User skips adding a backup phone	{ user_id }

Screen lifecycle

Event name	When it fires	Data
on_close	User closes the auth screen	—

Event constants

All event names are available as constants in SsoEventNames:

SsoEventNames.loginClick              // 'login_click'
SsoEventNames.signupClick             // 'signup_click'
SsoEventNames.providerClick           // 'provider_click'
SsoEventNames.invalidCredentials      // 'invalid_credentials'
SsoEventNames.successLogin            // 'success_login'
SsoEventNames.successSignup           // 'success_signup'
SsoEventNames.leftEmailVerificationPage  // 'left_email_verification_page'
SsoEventNames.leftPhoneVerificationPage  // 'left_phone_verification_page'
SsoEventNames.skippedBackupEmail      // 'skipped_backup_email'
SsoEventNames.skippedBackupPhone      // 'skipped_backup_phone'
SsoEventNames.onClose                 // 'on_close'

Suppressing events

You can suppress specific events:

SsoAnalyticsConfig(
  onEvent: (event) { /* ... */ },
  suppressedEvents: {
    SsoEventNames.providerClick,
  },
)

Example: Firebase Analytics

analytics: SsoAnalyticsConfig(
  onEvent: (event) {
    FirebaseAnalytics.instance.logEvent(
      name: event.name,
      parameters: event.properties.map(
        (k, v) => MapEntry(k, v.toString()),
      ),
    );
  },
  onError: (error) {
    FirebaseCrashlytics.instance.recordError(
      error,
      StackTrace.current,
      reason: 'SSO SDK error',
    );
  },
),