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

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

Başlamadan önce şunların yapıldığından 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
  }
}

Paywall açma

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’lerdeki paywalllarla çalışmanın en sorunsuz yolu, eylem ID’sini paywall placement ID’siyle 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
    }
}