Flow ve paywall olaylarını yönet - Capacitor

Flow Builder ile oluşturulan flow’lar ve paywalllar, satın alma yapmak ve geri yüklemek için ekstra kod gerektirmez. Ancak uygulamanızın yanıt verebileceği bazı olaylar üretirler. Bu olaylar arasında düğme basmaları (kapat düğmeleri, URL’ler, ürün seçimleri vb.) ve flow üzerinde gerçekleştirilen satın alma ile ilgili işlemlere dair bildirimler yer alır. Bu olaylara nasıl yanıt vereceğinizi aşağıda öğrenebilirsiniz.

Mobil uygulamanızda flow ekranında gerçekleşen süreçleri kontrol etmek veya izlemek için view.setEventHandlers metodunu uygulayın:

const view = await createFlowView(flow);

const unsubscribe = await view.setEventHandlers({
  onCloseButtonPress() {
    return true; // close the flow (default behavior)
  },
  onAndroidSystemBack() {
    return true; // close the flow; by default, it stays open
  },
  onPurchaseCompleted(purchaseResult, product) {
    return purchaseResult.type === 'success'; // close the flow on a successful purchase, keep it open for cancelled or pending purchases
  },
  onPurchaseStarted(product) { /***/ },
  onPurchaseFailed(error, product) { /***/ },
  onRestoreCompleted(profile) { /***/ },
  onRestoreFailed(error) { /***/ },
  onProductSelected(productId) { /***/ },
  onError(error) { /***/ },
  onLoadingProductsFailed(error) { /***/ },
  onUrlPress(url, openIn) {
    adapty.openWebUrl({ url, openIn }).catch(console.warn); // same as the SDK default
    return false; // keep the flow open
  },
  onAppeared(appearedView) { /***/ },
  onDisappeared() { /***/ },
  onWebPaymentNavigationFinished() { /***/ },
});

// onUrlPress
url;    // 'https://example.com/terms'
openIn; // 'browser_in_app' or 'browser_out_app'

// onCustomAction
actionId; // 'login'

// onProductSelected
productId; // 'premium_monthly'

// onAppeared
appearedView.id;          // '3f8a1c7e-9b24-4d51-8e30-6c5b2a9f1d47'
appearedView.placementId; // 'onboarding_paywall'
appearedView.variationId; // 'd21c4b6a-57e8-4f39-b0a2-8c7e13f5d94b'
appearedView.locale;      // 'es'

// onPurchaseStarted, onPurchaseCompleted, onPurchaseFailed
product.vendorProductId;        // 'premium_monthly'
product.localizedTitle;         // 'Premium Monthly'
product.localizedDescription;   // 'Premium subscription for 1 month'
product.price?.amount;          // 9.99
product.price?.currencyCode;    // 'USD'
product.price?.localizedString; // '$9.99'

// onPurchaseCompleted
purchaseResult.type; // 'success', 'pending', or 'user_cancelled'
if (purchaseResult.type === 'success') {
  purchaseResult.profile.accessLevels['premium']?.isActive; // true
}

// onRestoreCompleted
profile.accessLevels['premium']?.isActive; // true

// onPurchaseFailed, onRestoreFailed, onError, onLoadingProductsFailed
error.message; // 'Purchase failed due to insufficient funds'

İhtiyaç duyduğunuz event handler’ları kaydedebilir, ihtiyaç duymadıklarınızı atlayabilirsiniz. Bu sayede kullanılmayan event listener’lar oluşturulmaz. Zorunlu event handler yoktur.

Event handler’lar bir boolean döndürür. true döndürülürse görüntüleme süreci tamamlanmış sayılır; böylece flow ekranı kapanır ve bu view için event listener’lar kaldırılır. Bazı olay işleyicilerinin geçersiz kılabileceğiniz varsayılan davranışları vardır:

• onCloseButtonPress: Kapat düğmesine basıldığında flow’u kapatır.
• onUrlPress: Tıklanan URL’yi, builder’da ayarlanan Open in seçeneğine uyarak adapty.openWebUrl aracılığıyla yerel tarayıcıda açar ve flow’u açık tutar.
• onAndroidSystemBack: Back düğmesine basıldığında flow’u açık tutar. Kapatmak için true döndürün.
• onPurchaseCompleted: Satın alma tamamlandıktan sonra flow’u açık tutar. Kapatmak için true döndürün.
• onRestoreCompleted: Başarılı bir geri yüklemeden sonra flow’u açık tutar. Kapatmak için true döndürün.
• onError: Render işlemi başarısız olursa flow’u kapatır.

Olay yöneticileri

view argümanı

view argümanı, Capacitor SDK 4.0.2-beta.1 veya üstünü gerektirir. Tüm flow handler’ları arasında yalnızca onAppeared, görünümün kendisine ait bir açıklama alır — şu alanlardan oluşan bir FlowEventView nesnesi:

Analitik olaylar

view.setEventHandlers({
  onAnalytics(name, params) {
    return false; // keep the flow open
  },
});

Bir flow, kullanıcı ekranlarından birini her açtığında flow_screen_showed olayını raporlar. Adapty bu olayları kendi flow analitiğinde sayar ve uygulamanıza da iletir; böylece aynı dönüşüm hunisini kendi analitiğinizde oluşturabilirsiniz.

Bu olayda hem isBackendEvent hem de isCustomerEvent true değerini alır: Adapty saymaya devam eder ve uygulamanız da olayı alır.

Bu verilerle ne yapacağınızı öğrenmek için Flow ekranı görüntülemelerini izleme sayfasına bakın.

Observer mode’da satın alma işlemlerini yönetme

SDK’yı Observer mode (observerMode: true) ile etkinleştirdiyseniz ve Adapty tarafından oluşturulan bir flow sunuyorsanız, SDK satın alma işlemlerini sizin yerinize gerçekleştirmez. Kullanıcı satın alma veya geri yükleme düğmesine dokunduğunda SDK, onObserverPurchaseInitiated veya onObserverRestoreInitiated metodunu çağırır; böylece satın alma veya geri yükleme işlemini kendi kodunuzla gerçekleştirebilirsiniz. Tam kurulum için Observer mode’da flow’ları sunma konusuna bakın.

Paywall Builder ile yapılandırılmış paywalllar, satın alma ve geri yükleme işlemleri için ekstra kod gerektirmez. Ancak uygulamanızın yanıt verebileceği bazı olaylar üretirler. Bu olaylar; buton tıklamalarını (kapat butonları, URL’ler, ürün seçimleri vb.) ve paywallda gerçekleştirilen satın alma işlemlerine ilişkin bildirimleri kapsar. Bu olaylara nasıl yanıt vereceğinizi aşağıda öğrenebilirsiniz.

Mobil uygulamanızdaki paywall ekranında gerçekleşen süreçleri kontrol etmek veya izlemek için view.setEventHandlers metodunu uygulayın:

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
  onCloseButtonPress() {
    console.log('User closed paywall');
    return true; // Allow the paywall to close
  },
  onAndroidSystemBack() {
    console.log('User pressed back button');
    return true; // Allow the paywall to close
  }, 
  onAppeared() {
    console.log('Paywall appeared');
    return false; // Don't close the paywall
  }, 
  onDisappeared() {
    console.log('Paywall disappeared');
  },
  onPurchaseCompleted(purchaseResult, product) {
    console.log('Purchase completed:', purchaseResult);
    return purchaseResult.type !== 'user_cancelled'; // Close if not cancelled
  },
  onPurchaseStarted(product) {
    console.log('Purchase started:', product);
    return false; // Don't close the paywall
  },
  onPurchaseFailed(error, product) {
    console.error('Purchase failed:', error);
    return false; // Don't close the paywall
  },
  onRestoreCompleted(profile) {
    console.log('Restore completed:', profile);
    return true; // Close the paywall after successful restore
  },
  onRestoreFailed(error) {
    console.error('Restore failed:', error);
    return false; // Don't close the paywall
  },
  onProductSelected(productId) {
    console.log('Product selected:', productId);
    return false; // Don't close the paywall
  },
  onRenderingFailed(error) {
    console.error('Rendering failed:', error);
    return false; // Don't close the paywall
  },
  onLoadingProductsFailed(error) {
    console.error('Loading products failed:', error);
    return false; // Don't close the paywall
  },
  onUrlPress(url) {
    window.open(url, '_blank');
    return false; // Don't close the paywall
  },
});

// onCloseButtonPress
{
  "event": "close_button_press"
}

// onAndroidSystemBack
{
  "event": "android_system_back"
}

// onAppeared
{
  "event": "paywall_shown"
}

// onDisappeared
{
  "event": "paywall_closed"
}

// onUrlPress
{
  "event": "url_press",
  "url": "https://example.com/terms"
}

// onCustomAction
{
  "event": "custom_action",
  "actionId": "login"
}

// onProductSelected
{
  "event": "product_selected",
  "productId": "premium_monthly"
}

// onPurchaseStarted
{
  "event": "purchase_started",
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseCompleted - Success
{
  "event": "purchase_completed",
  "purchaseResult": {
    "type": "success",
    "profile": {
      "accessLevels": {
        "premium": {
          "id": "premium",
          "isActive": true,
          "expiresAt": "2024-02-15T10:30:00Z"
        }
      }
    }
  },
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseCompleted - Cancelled
{
  "event": "purchase_completed",
  "purchaseResult": {
    "type": "user_cancelled"
  },
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseFailed
{
  "event": "purchase_failed",
  "error": {
    "code": "purchase_failed",
    "message": "Purchase failed due to insufficient funds",
    "details": {
      "underlyingError": "Insufficient funds in account"
    }
  }
}

// onRestoreCompleted
{
  "event": "restore_completed",
  "profile": {
    "accessLevels": {
      "premium": {
        "id": "premium",
        "isActive": true,
        "expiresAt": "2024-02-15T10:30:00Z"
      }
    },
    "subscriptions": [
      {
        "vendorProductId": "premium_monthly",
        "isActive": true,
        "expiresAt": "2024-02-15T10:30:00Z"
      }
    ]
  }
}

// onRestoreFailed
{
  "event": "restore_failed",
  "error": {
    "code": "restore_failed",
    "message": "Purchase restoration failed",
    "details": {
      "underlyingError": "No previous purchases found"
    }
  }
}

// onRenderingFailed
{
  "event": "rendering_failed",
  "error": {
    "code": "rendering_failed",
    "message": "Failed to render paywall interface",
    "details": {
      "underlyingError": "Invalid paywall configuration"
    }
  }
}

// onLoadingProductsFailed
{
  "event": "loading_products_failed",
  "error": {
    "code": "products_loading_failed",
    "message": "Failed to load products from the server",
    "details": {
      "underlyingError": "Network timeout"
    }
  }
}

İhtiyaç duyduğunuz event handler’ları kaydedebilir, ihtiyaç duymadıklarınızı atlayabilirsiniz. Bu sayede kullanılmayan event listener’lar oluşturulmaz. Zorunlu event handler yoktur.

Event handler’lar bir boolean döndürür. true döndürülürse, gösterim süreci tamamlanmış sayılır; böylece paywall ekranı kapanır ve bu view için event listener’lar kaldırılır. Bazı event handler’ların, gerekirse geçersiz kılabileceğiniz varsayılan davranışları vardır:

• onCloseButtonPress: Kapat düğmesine basıldığında paywall’ı kapatır.
• onAndroidSystemBack: Geri düğmesine basıldığında paywall’ı kapatır.
• onRestoreCompleted: Başarılı bir restore işleminin ardından paywall’ı kapatır.
• onPurchaseCompleted: Kullanıcı iptal etmedikçe paywall’ı kapatır.
• onRenderingFailed: Paywall oluşturma başarısız olursa paywall’ı kapatır.
• onUrlPress: URL’leri sistem tarayıcısında açar ve paywall’ı açık tutar.

Olay işleyicileri