Capacitor SDK'da onboarding olaylarını yönetin
Onboardings, SDK v4’te kullanımdan kaldırılmıştır ve gelecekteki bir sürümde kaldırılacaktır. Artık hata düzeltmesi veya iyileştirme almamaktadır. Bunun yerine flow’ları kullanın: onboarding’lerin WebView içinde çalışmasının aksine, flow’lar cihazda yerel olarak render edilir — bu sayede daha akıcı animasyonlar, tutarlı bir native görünüm, daha hızlı yükleme süreleri ve WebView runtime bağımlılığı ortadan kalkar. Başlamak için Flow ve paywall’ları alma ve Flow ve paywall’ları gösterme konularına bakın.
Oluşturucuyla yapılandırılan onboarding’ler, uygulamanızın yanıt verebileceği olaylar üretir. Bağımsız ekran sunumu için bu olayları işlemek amacıyla setEventHandlers metodunu kullanın.
Başlamadan önce şunları yaptığınızdan emin olun:
- Bir onboarding oluşturdunuz.
- Onboarding’i bir placement’a eklediniz.
Olay işleyicilerini ayarlama
Onboarding olaylarını işlemek 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 düğmeye özel eylem ekleyebilir ve ona bir ID atayabilirsiniz.
Bu ID’yi kodunuzda kullanarak özel bir eylem olarak işleyebilirsiniz. Örneğin, kullanıcı Login veya Allow notifications gibi özel bir butona dokunduğunda, event handler actionId parametresiyle tetiklenir ve bu parametre builder’daki Action ID değeriyle eşleşir. “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
},
});Olay örneği (Genişletmek için tıklayın)
{
"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);
},
});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
Onboarding, kullanıcı Close eylemine atanmış bir düğmeye dokunduğunda kapalı sayılır.
Kullanıcı onboarding’i kapattığında ne olacağını yönetmeniz gerektiğini unutmayın. Örneğin, onboarding’in kendisini göstermeyi durdurmanız gerekir.
view.setEventHandlers({
onClose(actionId, meta) {
console.log('Onboarding closed:', actionId);
return true; // Onboarding'in kapanmasına izin ver
},
});Etkinlik ö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
}
}Bir paywall açma
Onboarding içinde bir paywall açmak istiyorsanız bu olayı ele alın. Paywall kapandıktan sonra açmak istiyorsanız daha doğrudan bir yol var: kapatma eylemini ele alın ve olay verisine dayanmadan bir paywall açın.
Onboarding’lerde paywall’larla çalışmanın en sorunsuz yolu, eylem 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österilebilir. Bir onboarding’in üzerine paywall sunarsanız, arka plandaki onboarding’i programatik olarak kontrol edemezsiniz. Onboarding’i kapatmaya çalışırsanız bunun yerine paywall kapanı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) {
// Ödeme ekranını göstermeden önce onboarding'i kapat
view.dismiss().then(() => {
openPaywall(actionId);
});
},
});
async function openPaywall(placementId: string) {
// Paywall açma mantığınızı buraya uygulayın
}Etkinlik ö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 flow’u 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:
| Tür | Açıklama |
|---|---|
onboardingStarted | Onboarding yüklendiğinde |
screenPresented | Herhangi bir ekran gösterildiğinde |
screenCompleted | Bir 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 işlem gerçekleştirdiğinde tetiklenir. |
secondScreenPresented | İkinci ekran gösterildiğinde |
userEmailCollected | Kullanıcının e-postası giriş alanı aracılığıyla toplandığında tetiklenir |
onboardingCompleted | Kullanıcı final ID’sine sahip bir ekrana ulaştığında tetiklenir. Bu olaya ihtiyaç duyuyorsanız son ekrana final ID’sini atayın. |
unknown | Tanınmayan herhangi bir olay türü için. name (bilinmeyen olayın adı) ve meta (ek meta veriler) içerir |
Her etkinlik, aşağıdakileri içeren meta bilgisini barındırır: |
| Alan | Açıklama |
|---|---|
onboardingId | Onboarding flow’unun benzersiz tanımlayıcısı |
screenClientId | Mevcut ekranın tanımlayıcısı |
screenIndex | Mevcut ekranın flow içindeki konumu |
screensTotal | Flow’daki toplam ekran sayısı |
Etkinlik ö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
}
}