Uygulamanız için özel Hızlı Ayarlar blokları oluşturma

Hızlı Ayarlar, Hızlı Ayarlar panelinde gösterilen ve kullanıcıların yinelenen görevleri hızlıca tamamlamak için dokunabileceği işlemleri temsil eden kartlardır. Uygulamanız, TileService sınıfı aracılığıyla kullanıcılara özel bir kart sağlayabilir ve kartın durumunu izlemek için bir Tile nesnesi kullanabilir. Örneğin, kullanıcıların uygulamanız tarafından sağlanan bir VPN'yi etkinleştirmesine veya devre dışı bırakmasına olanak tanıyan bir Kart oluşturabilirsiniz.

Şekil 1. VPN kutusunun açık ve kapalı olduğu Hızlı Ayarlar paneli.

Not: Bu kılavuzda yalnızca Wear dışı kutular ele alınmaktadır. Hızlı Ayarlar kutuları, Wear OS'te tanımlanan kutularla ilişkili değildir. Wear OS kartları için WearOS Kartları Kılavuzu'na bakın.

Kart oluşturmaya ne zaman karar vereceğinize karar verme

Kullanıcıların sıklıkla erişmesini beklediğiniz veya hızlı erişmesi gereken (veya her ikisi) belirli işlevler için kartlar oluşturmanızı öneririz. En etkili kartlar, sıklıkla gerçekleştirilen işlemlere hızlı erişim sağlayan ve bu iki özelliğe de uyan kartlardır.

Örneğin, bir fitness uygulaması için kullanıcıların hızlıca antrenman oturumu başlatmasına olanak tanıyan bir Kart oluşturabilirsiniz. Ancak aynı uygulama için kullanıcıların tüm antrenman geçmişlerini inceleyebilecekleri bir Kart oluşturmanızı önermeyiz.

Şekil 2. Bir fitness uygulaması için önerilen ve önerilmeyen kartlara örnekler.

Kartınızın bulunabilirliğini ve kullanım kolaylığını artırmak için belirli uygulamalardan kaçınmanızı öneririz:

• Uygulama başlatmak için kartları kullanmaktan kaçının. Bunun yerine uygulama kısayolu veya standart bir başlatıcı kullanın.

• Tek seferlik kullanıcı işlemleri için kart kullanmaktan kaçının. Bunun yerine uygulama kısayolu veya bildirim kullanın.

• Çok fazla kart oluşturmayın. Uygulama başına en fazla iki tane kullanmanızı öneririz. Bunun yerine uygulama kısayolu kullanın.

• Bilgi gösteren ancak kullanıcılar için etkileşimli olmayan kartlar kullanmaktan kaçının. Bunun yerine bildirim veya widget kullanın.

Kartınızı oluşturma

Kart oluşturmak için önce uygun bir kart simgesi oluşturmanız, ardından uygulamanızın manifest dosyasında TileService'nizi oluşturup bildirmeniz gerekir.

Not: Uygulamanız için TileService oluşturmak, uygulamayı kullanıcının Hızlı Ayarlar paneline eklemez. TileService, yalnızca kullanıcı karoyu ekledikten sonra karoyla bir arayüz görevi görür.

Hızlı Ayarlar örneği, bir karonun nasıl oluşturulacağını ve yönetileceğini gösteren bir örnektir.

Özel simgenizi oluşturun

Hızlı Ayarlar panelindeki kartta gösterilecek özel bir simge sağlamanız gerekir. (Bu simgeyi, sonraki bölümde açıklanan TileService öğesini tanımlarken eklersiniz.) Simge, şeffaf arka plana sahip düz beyaz renkte, 24 x 24 dp boyutunda ve VectorDrawable şeklinde olmalıdır.

Şekil 3. Vektörel çizilebilir öğe örneği.

Kartınızın amacını görsel olarak gösteren bir simge oluşturun. Bu sayede kullanıcılar, kartınızın ihtiyaçlarına uygun olup olmadığını kolayca belirleyebilir. Örneğin, kullanıcıların antrenman oturumu başlatmasına olanak tanıyan bir fitness uygulaması için bir karoda kronometre simgesi oluşturabilirsiniz.

TileService'inizi oluşturup tanımlama

Kartınız için TileService sınıfını genişleten bir hizmet oluşturun.

Kotlin

class MyQSTileService: TileService() {

  // Called when the user adds your tile.
  override fun onTileAdded() {
    super.onTileAdded()
  }
  // Called when your app can update your tile.
  override fun onStartListening() {
    super.onStartListening()
  }

  // Called when your app can no longer update your tile.
  override fun onStopListening() {
    super.onStopListening()
  }

  // Called when the user taps on your tile in an active or inactive state.
  override fun onClick() {
    super.onClick()
  }
  // Called when the user removes your tile.
  override fun onTileRemoved() {
    super.onTileRemoved()
  }
}

Java

public class MyQSTileService extends TileService {

  // Called when the user adds your tile.
  @Override
  public void onTileAdded() {
    super.onTileAdded();
  }

  // Called when your app can update your tile.
  @Override
  public void onStartListening() {
    super.onStartListening();
  }

  // Called when your app can no longer update your tile.
  @Override
  public void onStopListening() {
    super.onStopListening();
  }

  // Called when the user taps on your tile in an active or inactive state.
  @Override
  public void onClick() {
    super.onClick();
  }

  // Called when the user removes your tile.
  @Override
  public void onTileRemoved() {
    super.onTileRemoved();
  }
}

TileService iznini uygulamanızın manifest dosyasında beyan edin. TileService öğenizin adını ve etiketini, önceki bölümde oluşturduğunuz özel simgeyi ve uygun izni ekleyin.

 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"  // 18-character limit.
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

TileService'inizi yönetme

TileService'nizi oluşturup uygulama manifestinizde beyan ettikten sonra durumunu yönetmeniz gerekir.

TileService bir bağlama hizmetidir. TileService, uygulamanız tarafından istendiğinde veya sistemin onunla iletişim kurması gerektiğinde bağlanır. Tipik bir bağlı hizmet yaşam döngüsü aşağıdaki dört geri çağırma yöntemini içerir: onCreate(), onBind(), onUnbind() ve onDestroy(). Bu yöntemler, hizmet yeni bir yaşam döngüsü aşamasına her girdiğinde sistem tarafından çağrılır.

Önemli: TileService, tipik Service yaşam döngüsünden geçmeye devam eder. Ancak TileService, uygulamanızın yanıt vermesi gereken TileService'ye özgü yaşam döngüsü yöntemleri içerdiğinden diğer bağlı hizmetlerin çoğundan farklıdır.

TileService yaşam döngüsüne genel bakış

Bağlı hizmet yaşam döngüsünü kontrol eden geri çağırmalara ek olarak, TileService yaşam döngüsüne özgü diğer yöntemleri de uygulamanız gerekir. Service yaşam döngüsü yöntemleri ve TileService yaşam döngüsü yöntemleri iki ayrı asynkron iş parçacığında çağrıldığı için bu yöntemler onCreate() ve onDestroy() dışında çağrılabilir.

TileService yaşam döngüsü, TileService'niz yeni bir yaşam döngüsü aşamasına her girdiğinde sistem tarafından çağrılan aşağıdaki yöntemleri içerir:

• onTileAdded(): Bu yöntem yalnızca kullanıcı kartınızı ilk kez eklediğinde ve kaldırıp tekrar eklediğinde çağrılır. Tek seferlik başlatma işlemlerini bu sırada yapmanız önerilir. Ancak bu, gerekli tüm ilklendirme işlemlerini karşılamayabilir.

  Not: Kart oluşturulduğunda onTileAdded() çağrılmaz. Örneğin, cihaz yeniden başlatıldığında veya açıldığında onTileAdded() çağrılmaz. Bu durum, kart eklenmişse ve cihaz kapatılmadan önce kaldırılmamışsa geçerlidir.

• onStartListening() ve onStopListening(): Bu yöntemler, uygulamanız kartvizitinizi her güncellediğinde çağrılır ve sık sık çağrılır. TileService, onStartListening() ile onStopListening() arasında bağlı kalır. Bu sayede uygulamanız kartta değişiklik yapabilir ve güncelleme yayınlayabilir.

• onTileRemoved(): Bu yöntem yalnızca kullanıcı kartınızı kaldırırsa çağrılır.

Dikkat: Bu aşamalar art arda gerçekleşmeyebilir. onTileAdded(), kullanıcı tarafından kutunuz Hızlı Ayarlar paneline eklendiğinde yalnızca bir kez çağrılabilir. onStartListening() ve onStopListening(), TileService yaşam döngüsü boyunca birden çok kez çağrılabilir. Kullanıcı kartınızı Hızlı Ayarlar panelinden kaldırmazsa onTileRemoved() hiçbir zaman çağrılmaz.

Dinleme modu seçme

TileService cihazınız etkin modda veya etkin olmayan modda dinler. Etkin modu kullanmanızı öneririz. Bu modu uygulama manifest dosyasında belirtmeniz gerekir. Aksi takdirde TileService standart moddur ve belirtilmesi gerekmez.

TileService'ün onStartListening() ve onStopListening() yöntem çiftinin dışında olacağını varsaymayın.

Etkin mod (önerilen)

Kendi sürecindeki durumunu dinleyen ve izleyen bir TileService için etkin modu kullanın. Etkin moddaki bir TileService, onTileAdded(), onTileRemoved(), dokunma etkinlikleri ve uygulama işlemi tarafından istendiğinde bağlanır.

Kart durumunuz kendi işlemi tarafından güncellenmesi gerektiğinde TileService'ünüz bilgilendiriliyorsa etkin modu kullanmanızı öneririz. Hızlı Ayarlar paneli kullanıcı tarafından her görüntülendiğinde etkin karoların bağlanmaması gerektiğinden, bu karolar sistem üzerindeki yükü sınırlar.

Dinleme durumunun başlatılmasını istemek ve onStartListening() için geri arama almak üzere statik TileService.requestListeningState() yöntemi çağrılabilir.

Uygulamanızın manifest dosyasına META_DATA_ACTIVE_TILE ekleyerek etkin modu beyan edebilirsiniz.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
         android:value="true" />
    ...
</service>

Etkin olmayan mod

Etkin olmayan mod standart moddur. Kartınız kullanıcı tarafından görüldüğünde bağlanan TileService'ler etkin olmayan moddadır. Bu, TileService'ün kontrolü dışındaki zamanlarda oluşturulup yeniden bağlanabileceği anlamına gelir. Ayrıca, kullanıcı kartı görüntülemediğinde de bağlanma durumu kaldırılabilir ve kart yok edilebilir.

Kullanıcı Hızlı Ayarlar panelini açtıktan sonra uygulamanız onStartListening() için geri çağırma alır. Tile nesnenizi onStartListening() ile onStopListening() arasında istediğiniz kadar güncelleyebilirsiniz.

Dikkat: Etkin mod yerine etkin olmayan modu kullanırsanız kullanıcı Hızlı Ayarlar panelini her açtığında TileService'iniz bağlanabilir.

Etkin olmayan modu belirtmeniz gerekmez. Bunun için META_DATA_ACTIVE_TILE öğesini uygulamanızın manifest dosyasına eklemeniz yeterlidir.

Kart durumlarına genel bakış

Kullanıcılar kartınızı ekledikten sonra kartınız her zaman aşağıdaki durumlardan birinde bulunur.

• STATE_ACTIVE: Açık veya etkin durumu belirtir. Kullanıcı bu durumdayken karonuzla etkileşime geçebilir.

  Örneğin, kullanıcıların zamanlı bir egzersiz oturumu başlatmasına olanak tanıyan bir fitness uygulaması kartında STATE_ACTIVE, kullanıcının bir egzersiz oturumu başlattığı ve zamanlayıcının çalıştığı anlamına gelir.

• STATE_INACTIVE: Kapalı veya duraklatılmış durumu gösterir. Kullanıcı bu durumdayken karonuzla etkileşim kurabilir.

  Fitness uygulaması kartını örnek olarak tekrar kullanırsak STATE_INACTIVE durumundaki bir kart, kullanıcının antrenman oturumu başlatmadığı ancak isterse bunu yapabileceği anlamına gelir.

• STATE_UNAVAILABLE: Geçici olarak kullanılamayan durumu gösterir. Kullanıcı bu durumdayken karonuzla etkileşimde bulunamaz.

  Örneğin, STATE_UNAVAILABLE durumundaki bir kart, kartın şu anda kullanıcı tarafından kullanılamadığını gösterir.

  Dikkat: Şu anda kullanılamayan ancak daha sonra kullanılabilir duruma getirilebilecek kartlar için STATE_UNAVAILABLE simgesini kullanın. Bileşen kullanıcı tarafından bir daha kullanılamayacaksa COMPONENT_ENABLED_STATE_DISABLED değerini setComponentEnabledSetting() değerine iletin.

Sistem yalnızca Tile nesnenizin başlangıç durumunu ayarlar. Tile nesnesinin yaşam döngüsünün geri kalanında durumunu siz belirlersiniz.

Sistem, Tile nesnenizin durumunu yansıtmak için karo simgesini ve arka planını renklendirebilir. Tile STATE_ACTIVE olarak ayarlanmış nesneler en koyu, STATE_INACTIVE ve STATE_UNAVAILABLE ise giderek daha açıktır. Tam ton, üreticiye ve sürüme özeldir.

Şekil 4. Kutucuğun durumunu yansıtacak şekilde renklendirilmiş kutucuklar (sırasıyla etkin, etkin değil ve kullanılamıyor durumları).

Kartınızı güncelleme

onStartListening() numaralı telefondan geri arandıktan sonra kartınızı güncelleyebilirsiniz. Kartın moduna bağlı olarak, onStopListening() için geri arama yapılana kadar kartınız en az bir kez güncellenebilir.

Etkin modda, onStopListening() için geri çağırma çağrısı almadan önce karonuzu tam olarak bir kez güncelleyebilirsiniz. Etkin olmayan modda, kartınızı onStartListening() ile onStopListening() arasında istediğiniz kadar güncelleyebilirsiniz.

Not: Etkin mod, kartınızın kullanıcı tarafından görünür olup olmadığına bakılmaksızın kartınızı güncellemenize olanak tanır.

getQsTile() adresini arayarak Tile nesnenizi alabilirsiniz. Tile nesnenizin belirli alanlarını güncellemek için aşağıdaki yöntemleri çağırın:

• setContentDescription()
• setIcon()
• setLabel()
• setState()
• setStateDescription()
• setSubtitle()

Not: Uygulamanızın manifest dosyasında ayarlanan simge ve etiket, Hızlı Ayarlar panelindeki kartta gösterilen varsayılan değerlerdir. Ancak, karonuzu güncellerken setIcon() ve setLabel() yöntemlerini çağırarak alanları yeni değerlere ayarlayabilirsiniz.

Tile nesnesinin alanlarını doğru değerlere ayarladıktan sonra karonuzu güncellemek için updateTile() işlevini çağırmanız gerekir. Bu işlem, sistemin güncellenen karo verilerini ayrıştırmasını ve kullanıcı arayüzünü güncellemesini sağlar.

Kotlin

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
  super.onStartListening()
  val state = getStateFromService()
  qsTile.label = state.label
  qsTile.contentDescription = tile.label
  qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.icon = state.icon
  qsTile.updateTile()
}

Java

public class StateModel {
  final boolean enabled;
  final String label;
  final Icon icon;

  public StateModel(boolean e, String l, Icon i) {
    enabled = e;
    label = l;
    icon = i;
  }
}

@Override
public void onStartListening() {
  super.onStartListening();
  StateModel state = getStateFromService();
  Tile tile = getQsTile();
  tile.setLabel(state.label);
  tile.setContentDescription(state.label);
  tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setIcon(state.icon);
  tile.updateTile();
}

Dokunmaları işleme

Kartınız STATE_ACTIVE veya STATE_INACTIVE konumundaysa kullanıcılar bir işlem tetiklemek için kartınıza dokunabilir. Ardından sistem, uygulamanızın onClick() geri çağırma işlevini çağırır.

Uygulamanız onClick() için geri çağırma aldıktan sonra bir iletişim kutusu veya etkinlik başlatabilir, arka planda çalışmayı tetikleyebilir ya da kartınızın durumunu değiştirebilir.

Kotlin

var clicks = 0
override fun onClick() {
  super.onClick()
  counter++
  qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.label = "Clicked $counter times"
  qsTile.contentDescription = qsTile.label
  qsTile.updateTile()
}

Java

int clicks = 0;

@Override
public void onClick() {
  super.onClick();
  counter++;
  Tile tile = getQsTile();
  tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setLabel("Clicked " + counter + " times");
  tile.setContentDescription(tile.getLabel());
  tile.updateTile();
}

İletişim başlatma

showDialog(), Hızlı Ayarlar panelini daraltır ve bir iletişim kutusu gösterir. Ek giriş veya kullanıcı izni gerektiriyorsa işleminize bağlam bilgisi eklemek için bir iletişim kutusu kullanın.

Not: isLocked(), kullanıcının kilit ekranının gösterilip gösterilmediğini kontrol eder. isLocked() true değerini döndürdüğünde showDialog(), kilit ekranının altında yüklendiği için görünür bir iletişim kutusu göstermez.

Etkinlik başlatma

startActivityAndCollapse(), paneli daraltırken bir etkinlik başlatır. Bir iletişim kutusunda gösterilenden daha ayrıntılı bilgi görüntülemek istiyorsanız veya işleminiz son derece etkileşimliyse etkinlikler faydalıdır.

Uygulamanız önemli düzeyde kullanıcı etkileşimi gerektiriyorsa yalnızca son çare olarak etkinlik başlatmalıdır. Bunun yerine bir iletişim kutusu veya açma/kapatma düğmesi kullanmayı deneyin.

Bir karoya uzun basıldığında kullanıcı için Uygulama Bilgileri ekranı gösterilir. Bu davranışı geçersiz kılmak ve bunun yerine tercihleri ayarlamak için bir etkinlik başlatmak istiyorsanız etkinliklerinizden birine ACTION_QS_TILE_PREFERENCES ile <intent-filter> ekleyin.

Android API 28'den itibaren PendingIntent, Intent.FLAG_ACTIVITY_NEW_TASK'ye sahip olmalıdır:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}

Alternatif olarak, işareti belirli bir Activity bölümündeki AndroidManifest.xml alanına da ekleyebilirsiniz.

Kartınızı açma/kapatma olarak işaretleme

Kartınız temel olarak iki durumlu bir anahtar olarak çalışıyorsa (kartların en yaygın davranışı budur) kartı açma/kapatma olarak işaretlemenizi öneririz. Bu, işletim sistemine kartın davranışı hakkında bilgi sağlamaya ve genel erişilebilirliği iyileştirmeye yardımcı olur.

Kartınızı açma/kapatma özelliğine sahip olarak işaretlemek için TOGGLEABLE_TILE meta verilerini true olarak ayarlayın.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

Yalnızca güvenli şekilde kilitlenmiş cihazlarda güvenli işlemler yapma

Kartınız, kilitli cihazlarda kilit ekranının üst kısmında gösterilebilir. Kart hassas bilgiler içeriyorsa cihazın güvenli durumda olup olmadığını belirlemek için isSecure() değerini kontrol edin. TileService, davranışını buna göre değiştirir.

Kart işleminin kilitliyken yapılması güvenliyse kilit ekranının üst kısmında bir etkinlik başlatmak için startActivity() simgesini kullanın.

Kart işlemi güvenli değilse kullanıcıdan cihazının kilidini açmasını istemek için unlockAndRun() simgesini kullanın. İşlem başarılı olursa sistem, bu yönteme ilettiğiniz Runnable nesnesini yürütür.

Kullanıcıdan kartınızı eklemesini isteyin

Kartınızı manuel olarak eklemek için kullanıcıların birkaç adımı uygulaması gerekir:

1. Hızlı Ayarlar panelini açmak için aşağı kaydırın.
2. Düzenle düğmesine dokunun.
3. Kutunuzu bulana kadar cihazdaki tüm kutular arasında gezinin.
4. Kartınızı basılı tutup etkin kartlar listesine sürükleyin.

Kullanıcı, istediğiniz zaman kartınızı taşıyabilir veya kaldırabilir.

Android 13'ten itibaren, kullanıcıların kartınızı cihaza eklemesini çok daha kolaylaştırmak için requestAddTileService() yöntemini kullanabilirsiniz. Bu yöntemde, kullanıcılara kutunuzu doğrudan Hızlı Ayarlar panellerine ekleme isteğinde bulunulur. İstem, uygulama adını, sağlanan etiketi ve simgeyi içerir.

Şekil 5. Hızlı Ayarlar Yerleşimi API'si istemi.

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Geri çağırma, kartın eklenip eklenmediği, eklenmediği takdirde zaten mevcut olup olmadığı veya herhangi bir hata olup olmadığı hakkında bilgi içerir.

Kullanıcılara ne zaman ve ne sıklıkta istem göstereceğinize karar verirken kendi takdirinizi kullanın. requestAddTileService() işlevini yalnızca bağlama uygun şekilde çağırmanızı öneririz (ör. kullanıcı, kartınızın kolaylaştırdığı bir özellikle ilk kez etkileşime geçtiğinde).

Sistem, kullanıcı tarafından daha önce yeterince kez reddedilmişse belirli bir ComponentName için istekleri işlemeye son vermeyi seçebilir. Kullanıcı, bu hizmeti almak için kullanılan Context değerinden belirlenir. Bu değer, mevcut kullanıcıyla eşleşmelidir.

Not: Kartınızın bulunabilirliğini artırmak ve kullanıcının kartınızı Hızlı Ayarlar paneline ekleme yükünü azaltmak için requestAddTileService() işlevini çağırmanızı öneririz.