Flutter SDK'da onboarding olaylarını işleme

Builder ile yapılandırılan onboarding’ler, uygulamanızın yanıt verebileceği olaylar üretir. Bu olayları nasıl işleyeceğiniz, hangi sunum yaklaşımını kullandığınıza bağlıdır:

  • Tam ekran sunum: Tüm onboarding görünümlerindeki olayları işleyen global bir olay gözlemcisi kurulmasını gerektirir
  • Gömülü widget: Olayları doğrudan widget içindeki satır içi callback parametreleri aracılığıyla işler

Başlamadan önce şunlardan emin olun:

  1. Adapty Flutter SDK 3.8.0 veya üzeri sürümünü yüklediniz.
  2. Bir onboarding oluşturdunuz.
  3. Onboarding’i bir placement’a eklediniz.

Tam ekran sunum olayları

Olay gözlemcisini kurma

Tam ekran onboarding’ler için olayları işlemek üzere AdaptyUIOnboardingsEventsObserver’ı uygulayın ve sunmadan önce ayarlayın:

AdaptyUI().setOnboardingsEventsObserver(this);

try {
  await onboardingView.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Olayları işleme

Gözlemcinizde şu metodları uygulayın:

void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  // Onboarding finished loading
}

void onboardingViewDidFailWithError(
  AdaptyUIOnboardingView view,
  AdaptyError error,
) {
  // Handle loading errors
}

void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Handle close action
  view.dismiss();
}

void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Dismiss onboarding before presenting paywall
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

void onboardingViewOnCustomAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Handle custom actions
}

void onboardingViewOnStateUpdatedAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String elementId,
  AdaptyOnboardingsStateUpdatedParams params,
) {
  // Handle user input updates
}

void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  // Track analytics events
}

Gömülü widget olayları

AdaptyUIOnboardingPlatformView kullanırken, olayları doğrudan widget içindeki satır içi callback parametreleri aracılığıyla işleyebilirsiniz. Olayların hem widget callback’lerine hem de global gözlemciye (ayarlandıysa) gönderileceğini, ancak global gözlemcinin isteğe bağlı olduğunu unutmayın:

AdaptyUIOnboardingPlatformView(
  onboarding: onboarding,
  onDidFinishLoading: (meta) {
    // Onboarding finished loading
  },
  onDidFailWithError: (error) {
    // Handle loading errors
  },
  onCloseAction: (meta, actionId) {
    // Handle close action
  },
  onPaywallAction: (meta, actionId) {
    _openPaywall(actionId);
  },
  onCustomAction: (meta, actionId) {
    // Handle custom actions
  },
  onStateUpdatedAction: (meta, elementId, params) {
    // Handle user input updates
  },
  onAnalyticsEvent: (meta, event) {
    // Track analytics events
  },
)

Olay türleri

Aşağıdaki bölümler, hangi sunum yaklaşımını kullandığınızdan bağımsız olarak işleyebileceğiniz farklı olay türlerini açıklamaktadır.

Özel eylemleri işleme

Builder’da bir butona custom eylem ekleyip ona bir ID atayabilirsiniz.

ios-events-1.webp

Ardından bu ID’yi kodunuzda kullanarak özel eylem olarak işleyebilirsiniz. Örneğin, bir kullanıcı Login veya Allow notifications gibi özel bir butona dokunduğunda, onboardingController delegate metodu .custom(id:) durumuyla tetiklenecek ve actionId parametresi builder’daki Action ID olacaktır. “allowNotifications” gibi kendi ID’lerinizi oluşturabilirsiniz.

// Full-screen presentation
void onboardingViewOnCustomAction(
    AdaptyUIOnboardingView view,
    AdaptyUIOnboardingMeta meta,
    String actionId,
) {
    switch (actionId) {
        case 'login':
            _login();
            break;
        case 'allow_notifications':
            _allowNotifications();
            break;
    }
}

// Embedded widget
onCustomAction: (meta, actionId) {
    _handleCustomAction(actionId);
}
Olay örneği (Genişletmek için tıklayın)
{
  "actionId": "allowNotifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

Onboarding yüklemesini tamamlama

Bir onboarding yüklemeyi tamamladığında şu olay tetiklenecektir:

// Full-screen presentation
void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  print('Onboarding loaded: ${meta.onboardingId}');
}

// Embedded widget
onDidFinishLoading: (meta) {
  print('Onboarding loaded: ${meta.onboardingId}');
}
Olay örneği (Genişletmek için tıklayın)
{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}

Onboarding’i kapatma

Bir kullanıcı Close eylemi atanmış bir butona dokunduğunda onboarding kapatılmış sayılır.

ios-events-2.webp

Bir kullanıcı onboarding’i kapattığında ne olacağını yönetmeniz gerektiğini unutmayın. Örneğin, onboarding’in kendisini görüntülemeyi durdurmanız gerekir.

// Full-screen presentation
void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  await view.dismiss();
}

// Embedded widget
onCloseAction: (meta, actionId) {
  Navigator.of(context).pop();
}
Olay örneği (Genişletmek için tıklayın)
{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}

Paywall açma

Onboarding içinde bir paywall açmak istiyorsanız bu olayı işleyin. Paywall’ı onboarding kapatıldıktan sonra açmak istiyorsanız, daha basit bir yol var: kapatma eylemini işleyip olay verisine bağlı kalmadan bir paywall açın.

Bir kullanıcı paywall açan bir butona tıkladığında, manuel olarak ayarladığınız buton eylem ID’sini alırsınız. Onboarding’lerde paywall’larla çalışmanın en sorunsuz yolu, eylem ID’sini bir paywall placement ID’sine eşit yapmaktır:

iOS’ta ekranda aynı anda yalnızca bir görünüm (paywall veya onboarding) görüntülenebilir. Onboarding’in üzerine bir paywall sunarsanız, arka plandaki onboarding’i programatik olarak kontrol edemezsiniz. Onboarding’i kapatmaya çalışmak paywall’ı kapatacak ve onboarding görünür kalacaktır. Bunu önlemek için, her zaman paywall’ı sunmadan önce onboarding görünümünü kapatın.

// Full-screen presentation
void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Dismiss onboarding before presenting paywall
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

Future<void> _openPaywall(String actionId) async {
  // Implement your paywall opening logic here
}

// Embedded widget
onPaywallAction: (meta, actionId) {
  _openPaywall(actionId);
}
Olay örneği (Genişletmek için tıklayın)
{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

Navigasyonu izleme

Onboarding akışı sırasında çeşitli navigasyon ile ilgili olaylar gerçekleştiğinde bir analitik olayı alırsınız:

// Full-screen presentation
void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  trackEvent(event.type, meta.onboardingId);
}

// Embedded widget
onAnalyticsEvent: (meta, event) {
  trackEvent(event.type, meta.onboardingId);
}

event nesnesi aşağıdaki türlerden biri olabilir:

TürAçıklama
onboardingStartedOnboarding yüklendiğinde
screenPresentedHerhangi bir ekran gösterildiğinde
screenCompletedBir ekran tamamlandığında. İsteğe bağlı elementId (tamamlanan öğenin tanımlayıcısı) ve isteğe bağlı reply (kullanıcıdan gelen yanıt) içerir. Kullanıcılar ekrandan çıkmak için herhangi bir eylem gerçekleştirdiğinde tetiklenir.
secondScreenPresentedİkinci ekran gösterildiğinde
userEmailCollectedKullanıcının e-postası giriş alanı aracılığıyla toplandığında tetiklenir
onboardingCompletedKullanıcı final ID’sine sahip bir ekrana ulaştığında tetiklenir. Bu olaya ihtiyacınız varsa, son ekrana final ID’sini atayın.
unknownTanınmayan herhangi bir olay türü için. name (bilinmeyen olayın adı) ve meta (ek meta veri) içerir

Her olay şunu içeren meta bilgisini barındırır:

AlanAçıklama
onboardingIdOnboarding akışının benzersiz tanımlayıcısı
screenClientIdMevcut ekranın tanımlayıcısı
screenIndexMevcut ekranın akıştaki konumu
screensTotalAkıştaki toplam ekran sayısı
Olay örnekleri (Genişletmek için tıklayın)
// onboardingStarted
{
  "name": "onboarding_started",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
  }
}

// screenPresented

{
    "name": "screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "interests_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

// screenCompleted

{
    "name": "screen_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    },
    "params": {
        "element_id": "profile_form",
        "reply": "success"
    }
}

// secondScreenPresented

{
    "name": "second_screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// userEmailCollected

{
    "name": "user_email_collected",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// onboardingCompleted

{
    "name": "onboarding_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "final_screen",
        "screen_index": 3,
        "total_screens": 4
    }
}