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ı bir şekilde tamamlamak için dokunabilecekleri işlemleri temsil eden bloklardır. Uygulamanız, TileService sınıfı aracılığıyla kullanıcılara bir özel karo 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 VPN'yi açıp kapatmalarına olanak tanıyan bir kutu oluşturabilirsiniz.

Ne zaman karo oluşturacağınıza karar verme

Kullanıcıların sık sık erişmesini veya hızlı erişime ihtiyaç duymasını beklediğiniz belirli işlevler için kutular oluşturmanızı öneririz (ya da her ikisi için de). En etkili karolar, bu özelliklerin her ikisini de karşılayan öğelerdir ve sık yapılan işlemlere hızlı erişim sağlar.

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

Karonunuzun bulunabilirliğini ve kullanım kolaylığını iyileştirmek için belirli uygulamalardan kaçınmanızı öneririz:

• Bir uygulamayı başlatmak için kutulardan kaçının. Bunun yerine uygulama kısayolu veya standart bir başlatıcı kullanın.

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

• Çok fazla kutu oluşturmaktan kaçının. Uygulama başına en fazla iki kısayol kullanmanızı öneririz. Bunun yerine bir uygulama kısayolu kullanın.

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

Karonuzu oluşturun

Kutu oluşturmak için önce uygun bir kutu simgesi oluşturmanız, ardından uygulamanızın manifest dosyasında TileService öğenizi oluşturup beyan etmeniz gerekir.

Hızlı Ayarlar örneği, kutu oluşturup yönetmeyle ilgili bir örnek sağlar.

Özel simgenizi oluşturun

Bunun için, Hızlı Ayarlar panelindeki kutuda görüntülenen özel bir simge sağlamanız gerekir. (Bir sonraki bölümde açıklanan şekilde, TileService tanımlarken bu simgeyi ekleyeceksiniz.) Simge, şeffaf bir arka plana sahip düz beyaz renkte, 24 x 24 dp boyutunda ve VectorDrawable şeklinde olmalıdır.

Karonunuzun amacına dair görsel ipucu veren bir simge oluşturun. Bu, kullanıcıların karonunuzun ihtiyaçlarına uygun olup olmadığını kolayca belirlemelerine yardımcı olur. Örneğin, bir fitness uygulaması için, kullanıcıların antrenman oturumu başlatmasına olanak tanıyan, kutucuk için bir kronometre simgesi oluşturabilirsiniz.

TileService'inizi oluşturun ve tanımlayın

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

Uygulamanızın manifest dosyasında TileService 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>

Kart Hizmetinizi yönetin

Uygulama manifestinizde TileService tanımlayıp oluşturduktan sonra durumunu yönetmeniz gerekir.

TileService bağlı bir hizmettir. Uygulamanız istendiğinde veya sistemin onunla iletişim kurması gerektiğinde TileService ürününüz bağlanır. Tipik bir bağlı hizmet yaşam döngüsü şu 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ı hizmetin yaşam döngüsünü kontrol eden geri çağırmalara ek olarak, TileService yaşam döngüsüne özel başka yöntemler uygulamanız gerekir. Service yaşam döngüsü yöntemleri ve TileService yaşam döngüsü yöntemleri, iki ayrı eşzamansız iş parçacığında çağrıldığından bu yöntemler onCreate() ve onDestroy() dışında çağrılabilir.

TileService yaşam döngüsü, TileService cihazınız her yeni 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ı, karonuzu ilk kez eklediğinde ve karonuzu kaldırıp tekrar eklediğinde çağrılır. Bu, tek seferlik başlatma yapmak için en iyi zamandır. Ancak bu, gereken tüm başlatma süresini karşılamayabilir.

• onStartListening() ve onStopListening(): Bu yöntemler, uygulamanız kartı güncellediğinde ve sık sık çağrılır. TileService, onStartListening() ile onStopListening() arasında bağlı kalacağı için uygulamanızın kartı ve push güncellemelerini değiştirmesine izin verir.

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

Dinleme modu seçin

TileService cihazınız etkin veya aktif olmayan modda dinler. Uygulama manifest dosyasında beyan etmeniz gereken etkin modu kullanmanızı öneririz. Aksi takdirde TileService standart moddur ve beyan edilmesi gerekmez.

TileService cihazınızın, onStartListening() ve onStopListening() yöntem çiftinin dışında çalışacağını varsaymayın.

Etkin mod (önerilir)

Durumunu kendi işleminde dinleyen ve izleyen bir TileService için etkin modu kullanın. onTileAdded(), onTileRemoved(), dokunma etkinlikleri ve uygulama işlemi tarafından istendiğinde TileService etkin modda tutulur.

Karo durumunuzun kendi süreciyle güncellenmesi gerektiğinde TileService cihazınıza bildirim gönderilirse etkin modu öneririz. Etkin kutular, Hızlı Ayarlar panelinin kullanıcı için her görünür olduğunda bağlanmasına gerek olmadığı için sistem üzerindeki yükü sınırlar.

Dinleme durumunun başlatılmasını istemek ve onStartListening() öğesine geri arama almak için 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>

Aktif olmayan mod

Etkin olmayan mod, standart moddur. Karonuz kullanıcı tarafından görülebildiği her an bağlıysa TileService etkin olmayan moddadır. Bu, TileService ürününüzün zaman zaman kontrolü dışındaki şekilde oluşturulabileceği ve sınırlandırılabileceği anlamına gelir. Ayrıca, kullanıcı karoyu görüntülemediğinde bağlantısı kaldırılabilir ve kaldırılabilir.

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

Etkin olmayan modu bildirmeniz gerekmez. META_DATA_ACTIVE_TILE özelliğini uygulamanızın manifest dosyasına eklemeyin.

Parça durumlarına genel bakış

Bir kullanıcı tarafından eklenen karonuz her zaman aşağıdaki durumlardan birinde olur.

• STATE_ACTIVE: Etkin veya etkin durumda olduğunu gösterir. Kullanıcı bu durumdayken karonuzla etkileşimde bulunabilir.

  Örneğin, kullanıcıların süreli bir antrenman oturumu başlatmalarına olanak tanıyan bir fitness uygulaması kutusu için STATE_ACTIVE değeri, kullanıcının bir antrenman 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şimde bulunabilir.

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

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

  Örneğin, STATE_UNAVAILABLE metnindeki bir karo, kutunun bir nedenle kullanıcıya şu anda kullanılamayacağı anlamına gelir.

Sistem yalnızca Tile nesnenizin başlangıç durumunu ayarlar. Tile nesnesinin durumunu, kullanım ömrünün geri kalanında ayarlarsınız.

Sistem, Tile nesnenizin durumunu yansıtmak için karo simgesinin ve arka planın tonunu belirleyebilir. STATE_ACTIVE olarak ayarlanan Tile nesneleri en koyu renk, STATE_INACTIVE ve STATE_UNAVAILABLE ise giderek daha açık hale geliyor. Ton, üreticiye ve sürüme özeldir.

Kartınızı güncelleyin

onStartListening() numaralı telefon arandığında karonuzu güncelleyebilirsiniz. Kutu moduna bağlı olarak, onStopListening() adlı kişiye geri arama yapılana kadar karonuz en az bir kez güncellenebilir.

Etkin modda, onStopListening() adlı kullanıcıyı geri aramadan önce karonuzu sadece bir kez güncelleyebilirsiniz. Etkin olmayan modda, onStartListening() ile onStopListening() arasında karonuzu istediğiniz kadar güncelleyebilirsiniz.

Tile nesnenizi getQsTile() yöntemini çağırarak 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 ayarlamayı tamamladıktan sonra karonuzu güncellemek için updateTile() yöntemini çağırmanız gerekir. Bu işlem, sistemin güncellenmiş 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();
}

Saplı dokunma

Kartınız STATE_ACTIVE veya STATE_INACTIVE içindeyse kullanıcılar işlem tetiklemek için karonunuza dokunabilir. Sistem daha sonra uygulamanızın onClick() geri çağırma işlevini çağırır.

Uygulamanız onClick() numarasına geri arama aldığında iletişim kutusu veya etkinlik başlatabilir, arka plan çalışmasını tetikleyebilir ya da karonunuzun 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 kutusu başlat

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

Etkinlik başlatma

startActivityAndCollapse(), paneli daraltırken bir etkinlik başlatır. Bir iletişim kutusunda gösterilenden daha ayrıntılı bilgiler varsa veya işleminiz büyük ölçüde etkileşimliyse etkinlikler faydalıdır.

Uygulamanız önemli ölçüde kullanıcı etkileşimi gerektiriyorsa, uygulama yalnızca son çare olarak bir etkinliği başlatmalıdır. Bunun yerine, iletişim kutusu veya açma/kapatma işlevini kullanabilirsiniz.

Bir karta uzun süre dokunulduğunda, kullanıcının Uygulama Bilgileri ekranı açılır. Bu davranışı geçersiz kılmak ve bunun yerine tercihleri ayarlamaya yönelik bir etkinlik başlatmak için ACTION_QS_TILE_PREFERENCES ile gerçekleştirdiğiniz etkinliklerinizden birine <intent-filter> ekleyin.

Karonuzu etkinleştirilebilir olarak işaretleme

Temel olarak iki durumlu anahtar olarak çalışıyorsa karonuzu açma/kapatma düğmesi olarak işaretlemenizi öneririz (bu, kartların en yaygın davranışıdır). Bu, kartın işletim sistemine davranışı hakkında bilgi sağlamaya ve genel erişilebilirliği iyileştirmeye yardımcı olur.

Karonuzu açma/kapatma düğmesi 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>

Güvenli bir şekilde kilitlenmiş cihazlarda yalnızca güvenli işlemleri gerçekleştir

Karonuz kilitli cihazlardaki kilit ekranının üzerinde gösterilebilir. Kutu 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ştirmelidir.

Kutu işlemi, kilitliyken güvenli bir şekilde gerçekleştirilebilirse kilit ekranının üst kısmında bir etkinlik başlatmak için startActivity() özelliğini kullanın.

Parça işlemi güvenli değilse kullanıcıdan cihazının kilidini açmasını istemek için unlockAndRun() özelliğini kullanın. Başarılı olursa sistem, bu yönteme geçirdiğiniz Runnable nesnesini yürütür.

Kullanıcıdan karonuzu eklemesini isteyin

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

1. Hızlı Ayarlar panelini açmak için hızlıca aşağı kaydırın.
2. Düzenle düğmesine dokunun.
3. Karonuzu bulana kadar cihazlarındaki tüm karolarda ilerleyin.
4. Karonuzu basılı tutup etkin kutular listesine sürükleyin.

Kullanıcı ayrıca karonuzu dilediği zaman taşıyabilir veya kaldırabilir.

Android 13'ten itibaren, kullanıcıların karonuzu bir cihaza eklemelerini çok daha kolay hale getirmek için requestAddTileService() yöntemini kullanabilirsiniz. Bu yöntemde, kullanıcılardan karonuzu doğrudan Hızlı Ayarlar panellerine hızlı bir şekilde 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, karonun eklenip eklenmediği, zaten orada olup olmadığı veya herhangi bir hata oluşup oluşmadığıyla ilgili bilgileri içerir.

Kullanıcılara ne zaman ve ne sıklıkta istem göstereceğinize karar verirken şahsi karar verme yetkinizi kullanın. requestAddTileService() yöntemini yalnızca bağlam içinde (örneğin, kullanıcı, karonuzun desteklediği bir özellikle ilk kez etkileşime geçtiğinde) çağırmanızı öneririz.

Daha önce kullanıcı tarafından yeterli sayıda reddedilmişse sistem, belirli bir ComponentName için istekleri işlemeyi durdurmayı seçebilir. Kullanıcı, bu hizmeti almak için kullanılan Context aracılığıyla belirlenir ve geçerli kullanıcıyla eşleşmelidir.