Özellik bayrakları ve Canary modu

Media3, kitaplıklarında yeni optimizasyonlar, davranışsal iyileştirmeler ve mimari geliştirmeler sunar. Bu değişiklikler yayınlanmadan önce kapsamlı bir şekilde test edilip doğrulanır. Bununla birlikte Media3, uygulamalara yeni davranışların nasıl ve ne zaman benimseneceği konusunda kontrol sağlamak için Canary modunu temel alan merkezi bir özellik bayrakları altyapısı (androidx.media3.common.Flags) içerir.

Bu sayfada, Canary modunun ve özellik bayraklarının işleyiş şekli ve bunları uygulamanızda kullanarak sürümler arasında yükseltme risklerini azaltma, kontrollü kullanıma sunma işlemleri gerçekleştirme ve acil durum geri alma işlemlerini yapılandırma hakkında bilgi verilmektedir.

Genel Bakış

Canary modu, yeni sunulan ve doğrulanmış kitaplık iyileştirmelerini birleştirilmiş, genel bir açma/kapatma düğmesi altında gruplandırır:

  • Varsayılan olarak etkin: Standart Media3 sürümlerinde Canary modu varsayılan olarak etkindir (true). Bu sayede uygulamanız, güvenli performans iyileştirmelerinden, optimizasyonlardan ve yeni özelliklerden otomatik olarak yararlanır.
  • Kapsam dışında kalmayı seçme ve geri alma özelliği: Uygulamalar, Canary modunu genel olarak devre dışı bırakabilir veya çalışma zamanında belirli özellik bayraklarını ayrı ayrı geçersiz kılabilir.
  • Kablolama karmaşıklığı yok: İşaretler, common modülündeki merkezi Flags sınıfı aracılığıyla yönetilir. Bu sayede, farklı bileşenlerde özel ayarlayıcılara veya yapılandırma nesnelerine gerek kalmaz.

Uygulamanızda neden işaretleri kullanmalısınız?

Canary modu varsayılan olarak etkindir ancak Flags'i uygulamanızın yapılandırmasına veya deneme çerçevesine entegre etmek çeşitli avantajlar sağlar:

1. Sürüm yükseltme riskini azaltma

Üretim ortamında kitaplığın ana veya alt sürümlerini yükseltmek, belirli OEM cihazlarda ya da özel medya ardışık düzenlerinde beklenmedik etkileşimlere neden olabilir. Media3'ü güncellerken, sürümler arasında daha güvenli bir yükseltme akışı için Canary modunu ve uzaktan yapılandırmayı kullanabilirsiniz:

  1. Güncellemeyi Canary modu devre dışı olarak yayınlama: Canary modu kapalıyken yeni bir Media3 sürümü yayınlamak, önceki sürümün (Canary etkin) özellik grubunu kabaca korur. Bu sayede, yeni davranışları benimsemeden önce üretimde temel kitaplık kararlılığını ve genel hata düzeltmelerini doğrulayabilirsiniz.
  2. Canary modunu kademeli olarak etkinleştirin: Canary modunu kullanıcı grupları arasında aşamalı olarak etkinleştirmek (ör. %5 -> %25 -> %100) için uzaktan yapılandırmayı kullanın veya metrik etkisini ölçmek için A/B denemeleri yapın.
  3. Gerekirse geri alın: Belirli cihazlarda gerileme meydana gelirse acil durum uygulama sürümüne gerek kalmadan Canary modunu veya belirli işaret kimliğini uzaktan devre dışı bırakın.
  4. Varsayılan olarak benimseme: Doğrulandıktan sonra, daha önce doğrulanmış Canary özelliklerinin kalıcı hale geldiği bir sonraki sürüm yükseltmesine kadar Canary modunu varsayılan olarak etkin bırakın.

Kotlin

// Enable or disable Canary mode globally (defaults to true).
Flags.setCanaryModeEnabled(false)

Java

// Enable or disable Canary mode globally (defaults to true).
Flags.setCanaryModeEnabled(false);

2. Kontrollü aşamalı sürümler ve A/B testi

Kullanıcılarınızın %100'ünü aynı anda yeni kitaplık davranışlarına maruz bırakmak yerine Flags'yi uzak bir yapılandırma veya deneme sistemine bağlayabilirsiniz.

Canary modunu aşamalı olarak etkinleştirebilir (ör. kullanıcıların %5'i → %25'i → %100'ü) veya yeni optimizasyonların başlatma gecikmesi, yeniden arabelleğe alma oranı ve oynatma hataları gibi temel oynatma metrikleri üzerindeki etkisini ölçmek için A/B denemeleri yapabilirsiniz.

3. Uzaktan kapatma anahtarı ve hızlı geri alma

Üretim aşamasında belirli bir cihaz modelinde veya OS sürümünde regresyon meydana gelirse sunucu tarafı yapılandırmasını kullanarak Canary modunu (veya sorumlu olan belirli işaret kimliğini) uzaktan devre dışı bırakabilirsiniz. Bu işlem, acil bir uygulama düzeltmesi veya ikili sürüm gerektirmeden kitaplığı etkilenen kullanıcılar için hemen kararlı, eski yedek davranışına döndürür.

Canary modunu ve işaretleri yapılandırma

Flags API'si, genel Canary modunu ve ayrı ayrı işaret geçersiz kılma işlemlerini kontrol etmek için yöntemler sağlar.

Genel Canary modu

Canary modu kapsamındaki tüm geliştirmeleri etkinleştirmek veya devre dışı bırakmak için:

Kotlin

// Enable or disable Canary mode globally (defaults to true).
Flags.setCanaryModeEnabled(false)

Java

// Enable or disable Canary mode globally (defaults to true).
Flags.setCanaryModeEnabled(false);

Bağımsız işaretleri geçersiz kılma

Ayrıca, genel Canary modu ayarından bağımsız olarak belirli işaretleri açıkça etkinleştirebilir veya devre dışı bırakabilirsiniz:

Kotlin

// Explicitly enable an experimental flag.
Flags.enableFlag(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION)

// Explicitly disable a flag.
Flags.disableFlag(Flags.FLAG_DYNAMIC_SCHEDULING)

Java

// Explicitly enable an experimental flag.
Flags.enableFlag(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION);

// Explicitly disable a flag.
Flags.disableFlag(Flags.FLAG_DYNAMIC_SCHEDULING);

Açık geçersiz kılma işlemleri, her zaman genel Canary modu varsayılanına göre önceliklidir.

İşaretleme durumu kontrol ediliyor

Kodunuzda Canary modunun veya belirli bir işaretin etkin olup olmadığını kontrol etmek için:

Kotlin

// Query whether Canary mode is active globally.
val isCanaryActive = Flags.isCanaryModeEnabled()

// Query whether a specific flag is active.
val isFeatureActive = Flags.isEnabled(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION)

Java

// Query whether Canary mode is active globally.
boolean isCanaryActive = Flags.isCanaryModeEnabled();

// Query whether a specific flag is active.
boolean isFeatureActive = Flags.isEnabled(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION);

İşaret çözünürlüğü sırası

Media3, çalışma zamanında bir özelliğin etkin olup olmadığını kontrol ederken durumu aşağıdaki sırayla çözer:

  1. Açık çalışma zamanı geçersiz kılma: İşaret kimliği için enableFlag veya disableFlag çağrıldıysa bu geçersiz kılma değeri döndürülür.
  2. Statik kitaplık durumu: İşaret statik olarak devre dışı bırakılmışsa (örneğin, henüz Canary modu için hazır olmayan erken geliştirme aşamasındaki bir özellik) veya statik olarak etkinleştirilmişse (Canary modundan mezun olan ve geçici bir kapsam dışında kalmayı seçme yedeği olan bir özellik) bu statik değer döndürülür.
  3. Canary modu durumu: Aksi takdirde işaret, genel Canary modu ayarını izler (Canary modu true ise etkin, false ise devre dışı).

Başlatma gereksinimleri

Herhangi bir Media3 bileşenini (ör. ExoPlayer, Transformer veya MediaSession) örneklendirmeden önce işaretleri yapılandırın:

  • Erken kurulum: Uygulama başlatılırken (ör. Application.onCreate içinde) veya uygulamanızın medya katmanı başlatılmadan önce Flags yapılandırın.
  • İş parçacığı güvenliği: Media3 bileşenleri, örneklendirme sırasında işaretleri okur ve bu değerleri dahili oynatma ve işleme iş parçacıklarına yayar. İşaret yapılandırmasının Media3 bileşenleri oluşturulmadan önce yapıldığından emin olun. Oynatıcılar veya dönüştürücüler etkin bir şekilde çalışırken işaretlerin değiştirilmesi desteklenmez.

Uzaktan yapılandırma ile entegrasyon

Önerilen mimari, uzaktan yapılandırma platformunuzda üç parametre göstermektir:

  • media3_canary_mode_enabled (Boole): Canary modu için genel açma/kapatma düğmesi (varsayılan olarak true).
  • media3_force_enable_flags (Tam sayı listesi): Hedeflenen denemeler için zorunlu olarak etkinleştirilecek belirli işaret kimlikleri.
  • media3_force_disable_flags (Tam Sayı Listesi): Bir sorun tespit edilirse zorunlu olarak devre dışı bırakılacak belirli işaret kimlikleri.

Bu değerleri, başlatma sırasında oyuncu örnekleri oluşturmadan önce uygulayın:

Kotlin

fun initializeMedia3Flags(
  canaryModeEnabled: Boolean,
  forceEnabledFlags: List<Int>,
  forceDisabledFlags: List<Int>,
) {
  // 1. Set global Canary mode state.
  Flags.setCanaryModeEnabled(canaryModeEnabled)

  // 2. Apply explicit force-enable overrides.
  for (flagId in forceEnabledFlags) {
    Flags.enableFlag(flagId)
  }

  // 3. Apply explicit force-disable overrides (remote kill switch).
  for (flagId in forceDisabledFlags) {
    Flags.disableFlag(flagId)
  }
}

Java

public static void initializeMedia3Flags(
    boolean canaryModeEnabled,
    List<Integer> forceEnabledFlags,
    List<Integer> forceDisabledFlags) {
  // 1. Set global Canary mode state.
  Flags.setCanaryModeEnabled(canaryModeEnabled);

  // 2. Apply explicit force-enable overrides.
  for (int flagId : forceEnabledFlags) {
    Flags.enableFlag(flagId);
  }

  // 3. Apply explicit force-disable overrides (remote kill switch).
  for (int flagId : forceDisabledFlags) {
    Flags.disableFlag(flagId);
  }
}

Flag'lerle test etme

Özellik bayraklarından etkilenen kod yolları için birim testleri veya Robolectric testleri yazarken testlerin birbirlerinin statik durumunu kirletmemesi için androidx.media3.test.utils.Media3FlagsRule (media3-test-utils modülünde mevcuttur) kullanın.

Media3FlagsRule ile otomatik temizleme

Media3FlagsRule eklemek, her testten sonra tüm işaret geçersiz kılma işlemlerinin ve Canary modu değişikliklerinin otomatik olarak sıfırlanmasını sağlar:

Kotlin

class MyPlayerTest {

  @get:Rule val flagsRule = Media3FlagsRule(this)

  @Test
  fun playback_withFeatureFlagEnabled() {
    Flags.enableFlag(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION)
    // Run test with the flag enabled...
  }
}

Java

public static class MyPlayerTest {

  @Rule public final Media3FlagsRule flagsRule = new Media3FlagsRule(this);

  @Test
  public void playback_withFeatureFlagEnabled() {
    Flags.enableFlag(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION);
    // Run test with the flag enabled...
  }
}

Parametreli test

Parametreli testleri farklı işaret durumlarında çalıştırmak için Media3FlagsRule ile @BindFlag ve @BindCanaryMode ek açıklamalarını birleştirebilirsiniz:

Kotlin

class MyParameterizedPlayerTest {

  @BindCanaryMode var canaryMode: Boolean = false

  @BindFlag(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION) var perStreamProgression: Boolean = false

  @get:Rule val flagsRule = Media3FlagsRule(this)

  @Test
  fun playback() {
    // Flags are automatically set for each test parameter combination.
  }
}

Java

public static class MyParameterizedPlayerTest {

  @BindCanaryMode public boolean canaryMode;

  @BindFlag(Flags.FLAG_PER_STREAM_MEDIA_PROGRESSION)
  public boolean perStreamProgression;

  @Rule public final Media3FlagsRule flagsRule = new Media3FlagsRule(this);

  @Test
  public void playback() {
    // Flags are automatically set for each test parameter combination.
  }
}

Teşhis ve günlük kaydı

Media3, oynatma başlatma ve çalışma zamanında etkin işaretleri ve Canary modu durumlarını doğrulamak için teşhis araçları sağlar.

Başlatma günlükleri

Bir ExoPlayer örneği başlatıldığında, etkin Canary durumunu ve tüm açık geçersiz kılmaları kitaplık sürümüyle birlikte logcat'e yazdırır:

ExoPlayerImpl: Init 59a18ab [AndroidXMedia3/1.10.1] [flame, Pixel 4, Google, 33] [Canary:ON]

Geçersiz kılmalar etkinse yalnızca varsayılan durumdan sapmalar listelenir:

ExoPlayerImpl: Init 59a18ab [AndroidXMedia3/1.10.1] [flame, Pixel 4, Google, 33] [Canary:ON, Overrides: enabled=[1], disabled=[3]]

Programatik inceleme

Biçimlendirilmiş teşhis dizesini veya sorgu geçersiz kılma listelerini programatik olarak alabilirsiniz (örneğin, uygulamanızın kilitlenme raporlarına veya analizlerine işaret durumunu dahil etmek için):

Kotlin

// Get formatted string representing active Canary state and overrides.
val flagLogString = Flags.getLogString()

// Query explicit override IDs if needed.
val enabledFlags = Flags.getEnabledOverrides()
val disabledFlags = Flags.getDisabledOverrides()

Java

// Get formatted string representing active Canary state and overrides.
String flagLogString = Flags.getLogString();

// Query explicit override IDs if needed.
int[] enabledFlags = Flags.getEnabledOverrides();
int[] disabledFlags = Flags.getDisabledOverrides();

İşaretleme yaşam döngüsü

Media3'teki işaretler geçici olacak şekilde tasarlanmıştır:

  1. Geliştirme: Flags.java içinde bir işaret kimliğinin arkasına yeni bir optimizasyon veya özellik eklenir.
  2. Canary modu: Doğrulandıktan ve genel kullanıma hazır hale geldikten sonra özellik, sürümler genelinde Canary modunda etkin olur.
  3. Tanıtım ve Temizleme: Üretimde kararlılığı kanıtlayan bir bekleme süresinden sonra özellik, kitaplıkta kalıcı olarak etkinleştirilir ve işaret sabiti, yedek kod yolları ve koşullu kontroller kaldırılır.

Özellik bayrağıyla ilgili bir sorunla karşılaşırsanız lütfen AndroidX Media3 GitHub sorun izleyicisinde bir rapor oluşturun. Böylece ekip, kalıcı tanıtımdan önce sorunu çözebilir.