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

Hızlı Ayarlar, Hızlı Ayarlar panelinde görüntülenen ve kullanıcıların yinelenen görevleri hızlı bir şekilde tamamlamak için dokunabileceği işlemleri temsil eden kutulardır. Uygulamanız, TileService sınıfı aracılığıyla kullanıcılara özel bir kart sağlayabilir. Ayrıca, karonun 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.

Ne zaman kart oluşturacağınıza 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 bloklar, bu özelliklerin her ikisiyle de eşleşenlerdir 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ıca antrenman oturumu başlatmalarını sağlayacak bir kutu oluşturabilirsiniz. Ancak aynı uygulama için kullanıcıların tüm antrenman geçmişlerini gözden geçirmelerini sağlayacak bir kutu oluşturmalarını önermeyiz.

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

• Bir uygulamayı başlatmak için kutular 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 bir uygulama kısayolu veya bildirim kullanın.

• Çok fazla karo oluşturmaktan kaçının. Uygulama başına en fazla iki URL öneririz. Bunun yerine uygulama kısayolu kullanın.

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

Karonuzu oluşturun

Kart oluşturmak için önce uygun bir blok simgesi oluşturmanız, ardından uygulamanızın manifest dosyasında TileService öğesini 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örüntülenen özel bir simge sağlamanız gerekir. (Sonraki bölümde açıklandığı şekilde, TileService özelliğini tanımlarken bu simgeyi ekleyeceksiniz.) Simge, 24 x 24 dp boyutunda ve VectorDrawable biçiminde, şeffaf bir arka plana sahip tamamen beyaz renkte olmalıdır.

Karonuzun amacına dair görsel ipuçları sağlayan bir simge oluşturun. Bu sayede kullanıcılar karonuzun ihtiyaçlarına uygun olup olmadığını kolayca belirleyebilir. Örneğin, kullanıcıların antrenman oturumu başlatmalarına olanak tanıyan bir fitness uygulamasının kutusu için kronometre simgesi oluşturabilirsiniz.

TileService'inizi oluşturma ve bildirme

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>

TileService'inizi yönetme

Uygulama manifestinizde TileService oluşturup beyan ettikten sonra durumunu yönetmeniz gerekir.

TileService bağlı bir hizmettir. TileService, uygulamanız tarafından istendiğinde veya sistemin uygulamayla iletişim kurması gerektiğinde bağlayıcı olur. 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, hizmetin yeni bir yaşam döngüsü aşamasına her geçtiğ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ı 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ın yeni bir yaşam döngüsü aşamasına her geçtiğ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 kullanıcı, kartı kaldırıp tekrar eklerse çağrılır. Tek seferlik başlatma işlemi için en uygun zaman budur. Ancak bu işlem gereken tüm başlatma işlemlerini karşılamayabilir.

• onStartListening() ve onStopListening(): Bu yöntemler, uygulamanız kartı 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ı kalmaya devam ederek uygulamanızın kartı ve push güncellemelerini değiştirmesine izin veriyor.

• 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 modda veya etkin olmayan modda dinler. Uygulama manifest dosyasında belirtmeniz gereken etkin modu kullanmanızı öneririz. Aksi takdirde TileService standart moddur ve bildirilmesi gerekmez.

TileService öğenizin, onStartListening() ve onStopListening() yöntem çifti dışında kullanılabileceğini varsaymayın.

Etkin mod (önerilir)

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 durumunuzun kendi işlemi ile güncellenmesi gerektiğinde TileService cihazınıza bildirim gönderilirse etkin modu öneririz. Etkin karolar, Hızlı Ayarlar panelinin kullanıcı tarafından her görünür olduğunda bağlı olması gerekmediğinden sistem üzerindeki yükü sınırlandırır.

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. Karonuz kullanıcı tarafından her görünür olduğunda TileService bağlanmışsa etkin olmayan moddadır. Bu, TileService öğenizin kontrol edilemeyen zamanlarda oluşturulabileceği ve tekrar bağlanabileceği anlamına gelir. Ayrıca, kullanıcı kartı görüntülemediğinde de bağlantısı kaldırılabilir ve kaldırılabilir.

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

Etkin olmayan modu beyan etmeniz gerekmez. Uygulamanızın manifest dosyasına META_DATA_ACTIVE_TILE özelliğini eklememeniz yeterlidir.

Karo durumlarına genel bakış

Bir kullanıcı tarafından eklendikten sonra karo her zaman aşağıdaki durumlardan birinde olur.

• STATE_ACTIVE: Açık veya etkin durumunu belirtir. Kullanıcı bu durumdayken karonunuzla etkileşimde bulunabilir.

  Örneğin, kullanıcıların süreli antrenman oturumu başlatmasına izin veren bir fitness uygulama kutusu için STATE_ACTIVE, kullanıcının antrenman oturumu başlattığını ve zamanlayıcının çalıştığını gösterir.

• STATE_INACTIVE: Kapalı veya duraklatılmış durumu gösterir. Kullanıcı bu durumdayken karonunuzla etkileşimde bulunabilir.

  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ılamaz durumunu gösterir. Kullanıcı, bu durumdayken karonuzla etkileşimde bulunamaz.

  Örneğin, STATE_UNAVAILABLE bölgesindeki bir kutu, bir nedenden dolayı kullanıcının şu anda tarafından kullanılamayacağı anlamına gelir.

  iletin.

Sistem yalnızca Tile nesnenizin ilk durumunu ayarlar. Yaşam döngüsünün geri kalanında Tile nesnesinin durumunu ayarlarsınız.

Sistem, Tile nesnenizin durumunu yansıtmak için karo simgesi ve arka planın renk tonunu değiştirebilir. STATE_ACTIVE olarak ayarlanan Tile nesneleri en koyu ve STATE_INACTIVE ve STATE_UNAVAILABLE giderek daha açık hale geliyor. Renk, üreticiye ve sürüme bağlı olarak belirlenir.

Karonuzu güncelleme

onStartListening() sizi geri aradıktan sonra karonuzu güncelleyebilirsiniz. Kartın moduna bağlı olarak, onStopListening() geri çağırma alınana kadar karonuz en az bir kez güncellenebilir.

Etkin modda, onStopListening() numaralı telefona geri arama almadan önce karonuzu tam olarak bir kez güncelleyebilirsiniz. Etkin olmayan modda, karonuzu onStartListening() ile onStopListening() arasında istediğiniz kadar güncelleyebilirsiniz.

getQsTile() çağrısı yaparak 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 parça 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();
}

Ekrana dokunma

Kartınız STATE_ACTIVE veya STATE_INACTIVE içindeyse kullanıcılar karonuza dokunarak işlem tetikleyebilir. Daha sonra sistem, uygulamanızın onClick() geri çağırmasını çağırır.

Uygulamanız onClick() çağrısı aldığında bir iletişim veya etkinlik başlatabilir, arka planda çalışmayı tetikleyebilir ya da karonuzun 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 gerektiriyorsa 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 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, uygulama yalnızca son çare olarak bir etkinlik başlatmalıdır. Bunun yerine bir iletişim kutusu veya açma/kapatma düğmesini 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 ayarlamaya yönelik bir etkinlik başlatmak için ACTION_QS_TILE_PREFERENCES ile etkinliklerinizden birine <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, ilgili Activity bölümündeki AndroidManifest.xml bölümüne ekleyebilirsiniz.

Karonuzu açıp kapatılabilir olarak işaretleyin

Temel olarak iki durumlu anahtar (karoların en yaygın davranışı) işlevi görüyorsa karonuzu geçiş yapılabilir olarak işaretlemenizi öneririz. Bu, karonun işletim sistemine davranışı hakkında bilgi sağlamaya ve genel erişilebilirliği iyileştirmeye yardımcı olur.

Karonuzu geçiş yapılabilir 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 bir şekilde kilitlenen cihazlarda güvenli işlemler gerçekleştirme

Kartınız, kilitli cihazlarda kilit ekranının üzerinde 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.

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

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

Kullanıcıdan karonuzu eklemesini isteyin

Kullanıcıların, karonuzu manuel olarak eklemek için birkaç adımı uygulaması gerekir:

1. Aşağı kaydırarak Hızlı Ayarlar panelini açın.
2. Düzenle düğmesine dokunun.
3. Kartınızı bulana kadar cihazdaki tüm kartlar arasında ilerleyin.
4. Karonuzu basılı tutun ve etkin karolar listesine sürükleyin.

Kullanıcı, karonuzu istediği zaman 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. İstemde uygulama adı, sağlanan etiket ve simge yer alır.

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

Geri çağırma, karonun eklenip eklenmemesi, eklenmemesi, 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öndereceğinize karar verirken şahsi karar verme yetkinizi 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 reddedilmişse belirli bir ComponentName için yapılan isteklerin işlenmesini durdurmayı seçebilir. Kullanıcı, bu hizmeti almak için kullanılan Context temel alınarak belirlenir. Kullanıcı, geçerli kullanıcıyla eşleşmelidir.