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 açıp kapatmalarına olanak tanıyan bir kutu oluşturabilirsiniz.

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

Kullanıcıların sık erişmesini beklediğiniz veya hızlı erişmesi (ya da her ikisi) için de belirli işlevler için kutular 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ği de karşılayan 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.

Kartınızın bulunabilirliğini ve kullanım kolaylığını iyileştirmek 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 kutular kullanmaktan kaçının. Bunun yerine uygulama kısayolu veya bildirim kullanın.

• Çok fazla kart oluşturmaktan kaçını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.

Hızlı Ayarlar örneği, kart oluşturma ve yönetmeyle ilgili bir örnek sunar.

Ö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.

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.

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()
  }
}

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 izninizi 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.

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

Sınır hizmet yaşam döngüsünü kontrol eden geri çağırmalara ek olarak, TileService yaşam döngüsüne özgü başka yöntemler 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 gerçekleştirmeyebilir.

• onStartListening() ve onStopListening(): Bu yöntemler, uygulamanız kartvizitleri 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.

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 işleminde durumunu dinleyen ve izleyen bir TileService için etkin modu kullanın. Etkin moddaki TileService; onTileAdded(), onTileRemoved(), dokunma etkinlikleri ve uygulama işlemi tarafından istendiğinde bağlı.

Kart durumunuz kendi işlemiyle güncellendiğinde TileService'ünüz bilgilendirilecekse etkin modu kullanmanızı öneririz. Hızlı Ayarlar paneli kullanıcı tarafından her görüntülendiğinde etkin karoların bağlanmasına gerek olmadığından, etkin karolar sistem üzerindeki yükü sınırlar.

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

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

<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 öğenizin kontrolünün dışında zaman zaman oluşturulup tekrar 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.

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şim kurabilir.

  Ö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şime geçebilir.

  Fitness uygulaması kutusu örneğini tekrar kullanırsak, STATE_INACTIVE içindeki bir kutu, kullanıcının egzersiz oturumu başlatmadığını ancak isterse bunu yapabileceği anlamına gelir.

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

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

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 simgesine ve arka plana renk tonunu değiştirebilir. 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.

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, karonuzu onStartListening() ile onStopListening() arasında istediğiniz kadar güncelleyebilirsiniz.

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()

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.

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()
}

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();
}

Kola dokunma

Kartınız STATE_ACTIVE veya STATE_INACTIVE konumundaysa kullanıcılar bir işlem tetiklemek için kartınıza dokunabilir. Daha sonra sistem, uygulamanızın onClick() geri çağırmasını ç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.

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()
}

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.

Etkinlik başlatma

startActivityAndCollapse(), paneli daraltırken bir etkinlik başlatır. Bir iletişim kutusundan daha ayrıntılı bilgi gerekiyorsa veya işleminiz yüksek düzeyde etkileşimli olduğunda, etkinlikler yararlı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 kullanabilirsiniz.

Bir karta uzun dokunduğunuzda, kullanıcı ile ilgili Uygulama Bilgileri ekranı görüntülenir. 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 öğesini içermelidir:

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.

Karonuzu geçiş yapılabilir olarak işaretleyin

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, kartın işletim sistemine 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. Kutuda hassas bilgiler varsa cihazın güvenli durumda olup olmadığını belirlemek için isSecure() değerini kontrol edin. Ardından, TileService cihazınızın davranışını buna göre değiştirmesi gerekir.

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 karonuzu cihazlara eklemesini çok daha kolay hale getirmek için requestAddTileService() yöntemini kullanabilirsiniz. Bu yöntemde kullanıcılardan, karonuzu doğrudan Hızlı Ayarlar paneline hızlıca eklemeleri istenir. İstem, uygulama adını, sağlanan etiketi ve simgeyi içerir.

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() öğesini yalnızca bağlam içinde (ör. kullanıcı, karonuzun sağladığı bir özellikle ilk kez etkileşimde bulunduğunda) çağırmanızı öneririz.

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.