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.

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 ikisinin de) 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ğ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ı 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şturmaktan kaçının. Uygulama başına en fazla iki tane kullanmanızı öneririz. Bunun yerine uygulama kısayolu kullanın.

• Bilgi görüntüleyen 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, 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.

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

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ı ayarsız 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 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.

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

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

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

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

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

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.

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 gerektiren işlemlere bağlam bilgisi eklemek için iletişim kutusu kullanın.

Etkinlik başlatma

startActivityAndCollapse(), paneli daraltırken bir etkinlik başlatır. Etkinlikler, bir iletişim kutusunda gösterilenden daha ayrıntılı bilgi göstermeniz gerekiyorsa veya işleminiz son derece etkileşimliyse kullanışlı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 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.

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.