Capacitor SDK'da onboarding olaylarını yönetme

Builder ile yapılandırılan onboardinglar, uygulamanızın yanıt verebileceği olaylar üretir. Bu olayları bağımsız ekran sunumu için yönetmek amacıyla setEventHandlers metodunu kullanın.

Başlamadan önce şunlardan emin olun:

1. Bir onboarding oluşturdunuz.
2. Onboarding’i bir placement’a eklediniz.

Olay işleyicilerini ayarlama

Onboarding olaylarını yönetmek için view.setEventHandlers metodunu kullanın:

try {
  const view = await createOnboardingView(onboarding);
  
  view.setEventHandlers({
    onAnalytics(event, meta) {
      console.log('Analytics event:', event);
    },
    onClose(actionId, meta) {
      console.log('Onboarding closed:', actionId);
      return true; // Allow the onboarding to close
    },
    onCustom(actionId, meta) {
      console.log('Custom action:', actionId);
      return false; // Don't close the onboarding
    },
    onPaywall(actionId, meta) {
      console.log('Paywall action:', actionId);
      view.dismiss().then(() => {
        openPaywall(actionId);
      });
    },
    onStateUpdated(action, meta) {
      console.log('State updated:', action);
    },
    onFinishedLoading(meta) {
      console.log('Onboarding finished loading');
    },
    onError(error) {
      console.error('Onboarding error:', error);
    },
  });
  
  await view.present();
} catch (error) {
  console.error('Failed to present onboarding:', error);
}

Olay türleri

Aşağıdaki bölümler, yönetebileceğiniz farklı olay türlerini açıklamaktadır.

Özel eylemleri yönetme

Builder’da bir butona custom eylem ekleyip bu eyleme bir ID atayabilirsiniz.

Ardından bu ID’yi kodunuzda kullanarak özel eylem olarak yönetebilirsiniz. Örneğin, bir kullanıcı Login veya Allow notifications gibi özel bir butona dokunduğunda, olay işleyicisi builder’daki Action ID ile eşleşen actionId parametresiyle tetiklenir. “allowNotifications” gibi kendi ID’lerinizi oluşturabilirsiniz.

view.setEventHandlers({
  onCustom(actionId, meta) {
    switch (actionId) {
      case 'login':
        console.log('Login action triggered');
        break;
      case 'allow_notifications':
        console.log('Allow notifications action triggered');
        break;
    }
    return false; // Don't close the onboarding
  },
});

{
  "actionId": "allow_notifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

Onboarding yüklemesini tamamlama

Bir onboarding yüklemesi tamamlandığında bu olay tetiklenir:

view.setEventHandlers({
  onFinishedLoading(meta) {
    console.log('Onboarding loaded:', meta.onboardingId);
  },
});

{
    "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.

view.setEventHandlers({
  onClose(actionId, meta) {
    console.log('Onboarding closed:', actionId);
    return true; // Allow the onboarding to close
  },
});

{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}

Bir paywall açma

Onboarding’lerde paywall’larla çalışmanın en sorunsuz yolu, aksiyon ID’sini bir paywall placement ID’sine eşit yapmaktır. iOS’ta aynı anda yalnızca bir görünüm (paywall veya onboarding) ekranda gösterilebileceğini unutmayın. Bir onboarding’in üzerine paywall sunarsanız, arka plandaki onboarding’i programatik olarak kontrol edemezsiniz. Onboarding’i kapatmaya çalışmak bunun yerine paywall’ı kapatır ve onboarding görünür kalır. Bunu önlemek için, paywall’ı sunmadan önce her zaman onboarding görünümünü kapatın.

view.setEventHandlers({
  onPaywall(actionId, meta) {
    // Dismiss onboarding before presenting paywall
    view.dismiss().then(() => {
      openPaywall(actionId);
    });
  },
});

async function openPaywall(placementId: string) {
  // Implement your paywall opening logic here
}

{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

Navigasyonu takip etme

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

view.setEventHandlers({
  onAnalytics(event, meta) {
    console.log('Analytics event:', event.type, meta.onboardingId);
  },
});

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

Her olay şu bilgileri içeren meta verisi sağlar:

// 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
    }
}