Flutter - Flow ve paywall etkinliklerini yönetme

Flow ve Paywall Builder ile oluşturulan paywall’lar, 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; buton tıklamaları (kapatma düğmeleri, URL’ler, ürün seçimleri vb.) ve flow veya paywall üzerinde 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 flow veya paywall ekranında gerçekleşen süreçleri kontrol etmek veya izlemek için AdaptyUIFlowsEventsObserver metodlarını uygulayın ve herhangi bir ekran gösterilmeden önce observer’ı ayarlayın:

AdaptyUI().setFlowsEventsObserver(this);

Üç observer metodu zorunludur — sınıfınız bunlar olmadan derlenmez: flowViewDidFinishPurchase, flowViewDidFinishRestore ve flowViewDidReceiveError. Diğer tüm metodlar isteğe bağlıdır. Daha önce ayarlanmış bir observer’ı kaldırmak için setFlowsEventsObserver’a null geçin.

Aşağıdaki olay örnekleri, her nesne üzerinde mevcut olan özellikleri ve yorumlarda örnek değerleri göstermektedir.

Kullanıcı tarafından oluşturulan olaylar

Görünüm belirdi

Bu metot, flow veya paywall görünümü ekranda gösterildiğinde çağrılır.

void flowViewDidAppear(AdaptyUIFlowView view) {
}

Görünüm kayboldu

Bu metot, flow veya paywall görünümü ekrandan kaldırıldığında çağrılır.

void flowViewDidDisappear(AdaptyUIFlowView view) {
}

Ürün seçimi

Bir ürün satın alma için seçildiğinde (kullanıcı ya da sistem tarafından), bu metot çağrılır:

void flowViewDidSelectProduct(AdaptyUIFlowView view, String productId) {
}

void flowViewDidSelectProduct(AdaptyUIFlowView view, String productId) {
  // productId is a String:
  productId; // 'premium_monthly'
}

Satın alma başlatıldı

Bir kullanıcı satın alma sürecini başlatırsa bu metot çağrılır:

void flowViewDidStartPurchase(AdaptyUIFlowView view, AdaptyPaywallProduct product) {
}

void flowViewDidStartPurchase(AdaptyUIFlowView view, AdaptyPaywallProduct product) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId;        // 'premium_monthly'
  product.localizedTitle;         // 'Premium Monthly'
  product.localizedDescription;   // 'Premium subscription for 1 month'
  product.price.amount;           // 9.99            (double)
  product.price.currencyCode;     // 'USD'
  product.price.localizedString;  // '$9.99'
}

Tamamlanan satın alma

Bu yöntem zorunludur. Bir satın alma başarıyla tamamlandığında, kullanıcı satın almayı iptal ettiğinde veya satın alma işlemi beklemede göründüğünde çağrılır:

void flowViewDidFinishPurchase(AdaptyUIFlowView view, 
                               AdaptyPaywallProduct product, 
                               AdaptyPurchaseResult purchaseResult) {
    switch (purchaseResult) {
      case AdaptyPurchaseResultSuccess(profile: final profile):
        // successful purchase
        break;
      case AdaptyPurchaseResultPending():
        // purchase is pending
        break;
      case AdaptyPurchaseResultUserCancelled():
        // user cancelled the purchase
        break;
      default:
        break;
    }
}

void flowViewDidFinishPurchase(AdaptyUIFlowView view,
                               AdaptyPaywallProduct product,
                               AdaptyPurchaseResult purchaseResult) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId; // 'premium_monthly'

  switch (purchaseResult) {
    case AdaptyPurchaseResultSuccess(profile: final profile):
      // profile — AdaptyProfile:
      profile.accessLevels['premium']?.isActive;  // true
      profile.accessLevels['premium']?.expiresAt; // DateTime(2027, 2, 15, 10, 30)
      break;
    case AdaptyPurchaseResultPending():
      // no additional data
      break;
    case AdaptyPurchaseResultUserCancelled():
      // no additional data
      break;
  }
}

Web ödeme navigasyonu tamamlandı

Bu metod, belirli bir ürün için bir web paywall açma girişiminin ardından çağrılır. Hem başarılı hem de başarısız navigasyon girişimleri dahildir:

void flowViewDidFinishWebPaymentNavigation(AdaptyUIFlowView view, 
                                           AdaptyPaywallProduct? product, 
                                           AdaptyError? error) {
}

Parametreler:

Başarısız satın alma

Bu yöntem, bir satın alma başarısız olduğunda (örneğin, ödeme sorunları veya ağ hataları nedeniyle) çağrılır. Kullanıcının başlattığı iptaller veya bekleyen işlemler için tetiklenmez — bunlar flowViewDidFinishPurchase tarafından ele alınır:

void flowViewDidFailPurchase(AdaptyUIFlowView view, 
                             AdaptyPaywallProduct product, 
                             AdaptyError error) {
}

Geri yükleme başlatıldı

Bir kullanıcı geri yükleme işlemini başlatırsa bu yöntem çağrılır:

void flowViewDidStartRestore(AdaptyUIFlowView view) {
}

Başarılı geri yükleme

Bu metod zorunludur. Bir satın alma geri yükleme işlemi başarılı olursa çağrılır:

void flowViewDidFinishRestore(AdaptyUIFlowView view, AdaptyProfile profile) {
}

void flowViewDidFinishRestore(AdaptyUIFlowView view, AdaptyProfile profile) {
  // profile — AdaptyProfile:
  profile.accessLevels['premium']?.isActive;            // true
  profile.accessLevels['premium']?.expiresAt;           // DateTime(2027, 2, 15, 10, 30)
  profile.subscriptions['premium_monthly']?.isActive;   // true
  profile.subscriptions['premium_monthly']?.expiresAt;  // DateTime(2027, 2, 15, 10, 30)
}

Kullanıcının gerekli accessLevel’a sahip olması durumunda ekranı kapatmanızı öneririz. Bunu nasıl kontrol edeceğinizi öğrenmek için Abonelik durumu konusuna, ekranı nasıl kapatacağınızı öğrenmek için ise Buton eylemlerine yanıt verme konusuna bakın.

Başarısız geri yükleme

Bir satın alma geri yüklemesi başarısız olursa şu metod çağrılır:

void flowViewDidFailRestore(AdaptyUIFlowView view, AdaptyError error) {
}

Veri çekme ve render etme

Ürün yükleme hataları

Başlatma sırasında ürün dizisini geçmezseniz, AdaptyUI gerekli nesneleri sunucudan kendisi alır. Bu işlem başarısız olursa, AdaptyUI hatayı şu metodu çağırarak bildirir:

void flowViewDidFailLoadingProducts(AdaptyUIFlowView view, AdaptyError error) {
}

Görünüm hataları

Bu yöntem zorunludur. v3’teki paywallViewDidFailRendering yönteminin yerini alır: arayüz oluşturma sırasında meydana gelen hatalar ve diğer görünüm hataları bu yöntem çağrılarak raporlanır. Bir kez uyguladığınızda, kapatma işlemi size kalmıştır — bu tür hatalarda görünümü kapatmanızı öneririz; hiçbir gözlemci ayarlanmadığında SDK’nın yerleşik varsayılanı da bunu yapar:

void flowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) {
  // log the error and dismiss the broken view
  view.dismiss();
}

Normal bir durumda render hataları oluşmamalıdır; eğer biriyle karşılaşırsanız lütfen bize bildirin.

Analitik olayları

İsteğe bağlı flowViewDidReceiveAnalyticEvent metodu, bir flow’dan gelen özel analitik olaylar için ayrılmıştır. Flow’lar henüz bu olayları kodunuza iletmediğinden, bu metodu uygulamanıza gerek yoktur.

Observer mode’da satın almaları yönetme

SDK’yı Observer mode’da etkinleştirdiyseniz ve Adapty tarafından oluşturulan bir flow veya paywall sunuyorsanız, SDK satın alma işlemlerini sizin adınıza gerçekleştirmez. Kullanıcı satın alma veya geri yükleme düğmesine dokunduğunda SDK, AdaptyUIObserverModeResolver’ınızı çağırır. Tam kurulum için bkz. Observer mode’da flow sunma.

Sistem isteklerini yönetme

AdaptyUISystemRequestsHandler (AdaptyUI().setSystemRequestsHandler(...) aracılığıyla kaydedilir), bir flow’dan gelen sistem istekleri için ayrılmıştır: işletim sistemi izin istemleri (push bildirimleri veya kamera erişimi gibi) ve App Store inceleme istekleri. Flow’lar henüz bu istekleri tetiklemiyor, dolayısıyla bir handler kaydetmeniz gerekmiyor. Eğer birini kayıt ederseniz, handlePermission’ın sınıfın zorunlu metodu olduğunu unutmayın — izni kendi kodunuzla isteyin, ardından AdaptyUIPermissionResult.granted() veya AdaptyUIPermissionResult.denied() döndürün; handleAppReviewRequest ise isteğe bağlıdır.

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ı (kapatma butonları, URL’ler, ürün seçimleri vb.) ve paywall’da gerçekleştirilen satın alma ile ilgili eylemlerin bildirimlerini içerir. 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 AdaptyUIPaywallsEventsObserver metodlarını uygulayın ve herhangi bir ekran gösterilmeden önce observer’ı ayarlayın:

AdaptyUI().setPaywallsEventsObserver(this);

Aşağıdaki olay örnekleri, her nesnede bulunan özellikleri ve yorumlarda açıklayıcı değerleri göstermektedir.

Kullanıcı tarafından tetiklenen olaylar

Paywall göründü

Bu yöntem, paywall görünümü ekranda gösterildiğinde çağrılır.

void paywallViewDidAppear(AdaptyUIPaywallView view) {
}

Paywall kayboldu

Bu yöntem, paywall görünümü ekrandan kaldırıldığında çağrılır.

void paywallViewDidDisappear(AdaptyUIPaywallView view) {
}

Ürün seçimi

Bir ürün satın alma için seçildiğinde (kullanıcı veya sistem tarafından), bu metod çağrılır:

void paywallViewDidSelectProduct(AdaptyUIPaywallView view, String productId) {
}

void paywallViewDidSelectProduct(AdaptyUIPaywallView view, String productId) {
  // productId is a String:
  productId; // 'premium_monthly'
}

Satın alma başlatıldı

Bir kullanıcı satın alma işlemini başlatırsa bu metod çağrılır:

void paywallViewDidStartPurchase(AdaptyUIPaywallView view, AdaptyPaywallProduct product) {
}

void paywallViewDidStartPurchase(AdaptyUIPaywallView view, AdaptyPaywallProduct product) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId;        // 'premium_monthly'
  product.localizedTitle;         // 'Premium Monthly'
  product.localizedDescription;   // 'Premium subscription for 1 month'
  product.price.amount;           // 9.99            (double)
  product.price.currencyCode;     // 'USD'
  product.price.localizedString;  // '$9.99'
}

Tamamlanan satın alma

Bu metot, bir satın alma işlemi başarıyla tamamlandığında, kullanıcı satın alma işlemini iptal ettiğinde veya satın alma işlemi beklemede göründüğünde çağrılır:

void paywallViewDidFinishPurchase(AdaptyUIPaywallView view, 
                                  AdaptyPaywallProduct product, 
                                  AdaptyPurchaseResult purchaseResult) {
    switch (purchaseResult) {
      case AdaptyPurchaseResultSuccess(profile: final profile):
        // successful purchase
        break;
      case AdaptyPurchaseResultPending():
        // purchase is pending
        break;
      case AdaptyPurchaseResultUserCancelled():
        // user cancelled the purchase
        break;
      default:
        break;
    }
}

void paywallViewDidFinishPurchase(AdaptyUIPaywallView view,
                                  AdaptyPaywallProduct product,
                                  AdaptyPurchaseResult purchaseResult) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId; // 'premium_monthly'

  switch (purchaseResult) {
    case AdaptyPurchaseResultSuccess(profile: final profile):
      // profile — AdaptyProfile:
      profile.accessLevels['premium']?.isActive;  // true
      profile.accessLevels['premium']?.expiresAt; // DateTime(2027, 2, 15, 10, 30)
      break;
    case AdaptyPurchaseResultPending():
      // no additional data
      break;
    case AdaptyPurchaseResultUserCancelled():
      // no additional data
      break;
  }
}

Bu durumda ekranı kapatmanızı öneririz. Bir paywall ekranını kapatma hakkında ayrıntılı bilgi için Düğme eylemlerine yanıt verme bölümüne bakın.

Web ödeme gezintisi tamamlandı

Bu metot, belirli bir ürün için web paywall açma girişiminin ardından çağrılır. Başarılı ve başarısız gezinti girişimlerinin her ikisini de kapsar:

void paywallViewDidFinishWebPaymentNavigation(AdaptyUIPaywallView view, 
                                               AdaptyPaywallProduct? product, 
                                               AdaptyError? error) {
}

Parametreler:

void paywallViewDidFinishWebPaymentNavigation(AdaptyUIPaywallView view,
                                               AdaptyPaywallProduct? product,
                                               AdaptyError? error) {
  // product — AdaptyPaywallProduct?:
  product?.vendorProductId; // 'premium_monthly'

  if (error == null) {
    // navigation succeeded
  } else {
    // error — AdaptyError:
    error.code;    // AdaptyErrorCode.networkFailed (2005)
    error.message; // 'Network request failed'
    error.detail;  // platform-specific underlying error, or null
  }
}

Başarısız satın alma

Bu yöntem, bir satın alma işlemi başarısız olduğunda (örneğin, ödeme sorunları veya ağ hataları nedeniyle) çağrılır. Kullanıcının iptal ettiği veya beklemedeki işlemler için tetiklenmez; bunlar paywallViewDidFinishPurchase tarafından işlenir:

void paywallViewDidFailPurchase(AdaptyUIPaywallView view, 
                                AdaptyPaywallProduct product, 
                                AdaptyError error) {
}

void paywallViewDidFailPurchase(AdaptyUIPaywallView view,
                                AdaptyPaywallProduct product,
                                AdaptyError error) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId; // 'premium_monthly'

  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.productPurchaseFailed (1006)
  error.message; // 'Product purchase failed.'
  error.detail;  // platform-specific underlying error, or null
}

Geri yükleme başlatıldı

Bir kullanıcı geri yükleme işlemini başlatırsa bu metot çağrılır:

void paywallViewDidStartRestore(AdaptyUIPaywallView view) {
}

Başarılı geri yükleme

Bir satın alma başarıyla geri yüklenirse şu metot çağrılır:

void paywallViewDidFinishRestore(AdaptyUIPaywallView view, AdaptyProfile profile) {
}

void paywallViewDidFinishRestore(AdaptyUIPaywallView view, AdaptyProfile profile) {
  // profile — AdaptyProfile:
  profile.accessLevels['premium']?.isActive;            // true
  profile.accessLevels['premium']?.expiresAt;           // DateTime(2027, 2, 15, 10, 30)
  profile.subscriptions['premium_monthly']?.isActive;   // true
  profile.subscriptions['premium_monthly']?.expiresAt;  // DateTime(2027, 2, 15, 10, 30)
}

Kullanıcının gerekli accessLevel’a sahip olması durumunda ekranı kapatmanızı öneririz. Bunu nasıl kontrol edeceğinizi öğrenmek için Abonelik durumu konusuna, paywall ekranını nasıl kapatacağınızı öğrenmek için Düğme eylemlerine yanıt verme konusuna bakın.

Geri yükleme başarısız oldu

Bir satın alma geri yüklemesi başarısız olursa bu metot çağrılır:

void paywallViewDidFailRestore(AdaptyUIPaywallView view, AdaptyError error) {
}

void paywallViewDidFailRestore(AdaptyUIPaywallView view, AdaptyError error) {
  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.receiveRestoredTransactionsFailed (1011)
  error.message; // 'Error occurred in the process of restoring purchases.'
  error.detail;  // platform-specific underlying error, or null
}

Veri getirme ve render etme

Ürün yükleme hataları

Başlatma sırasında ürün dizisini geçmezseniz, AdaptyUI gerekli nesneleri sunucudan kendisi alır. Bu işlem başarısız olursa AdaptyUI, hatayı şu metodu çağırarak bildirir:

void paywallViewDidFailLoadingProducts(AdaptyUIPaywallView view, AdaptyError error) {
}

void paywallViewDidFailLoadingProducts(AdaptyUIPaywallView view, AdaptyError error) {
  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.productRequestFailed (1002)
  error.message; // 'Unable to fetch available In-App Purchase products at the moment.'
  error.detail;  // platform-specific underlying error, or null
}

Render hataları

Arayüz oluşturma sırasında bir hata oluşursa, bu metot çağrılarak hata bildirilir. Varsayılan olarak (v3.15.2’den itibaren), oluşturma hatası meydana geldiğinde paywall otomatik olarak kapatılır; ancak gerekirse bu davranışı değiştirebilirsiniz.

void paywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) {
  // Default behavior: view.dismiss()
  // Override with custom logic if needed, for example:
  // - Log the error
  // - Show an error message to the user
}

void paywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) {
  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.jsException (4105)
  error.message; // 'An exception was thrown from JS during AdaptyUI flow execution.'
  error.detail;  // platform-specific underlying error, or null

  // Default behavior: view.dismiss()
}

Normal şartlarda böyle hatalarla karşılaşılmamalıdır; eğer bununla karşılaşırsanız lütfen bize bildirin.