Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

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

Hızlı Ayarlar, Hızlı Ayarlar panelinde gösterilen ve işlemleri temsil eden kutulardır. Kullanıcılar, yinelenen görevleri hızlıca tamamlamak için bu kutulara dokunabilir. Uygulamanız, TileService sınıfı aracılığıyla kullanıcılara özel bir kutu sağlayabilir ve kutunun 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 kapatmasına olanak tanıyan bir kutu oluşturabilirsiniz.

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

Kart oluşturma zamanına karar verme

Kullanıcıların sık sık erişmesini veya hızlı erişmesini (ya da her ikisini birden) beklediğiniz belirli işlevler için kartlar oluşturmanızı öneririz. En etkili kartlar, bu iki özelliğe de sahip olan ve sık yapılan işlemlere hızlı erişim sağ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şini incelemesine olanak tanıyan bir kart oluşturmanızı önermeyiz.

Fitness uygulaması kartı kullanım alanları — **Şekil 2.** Bir fitness uygulaması için önerilen ve önerilmeyen kart örnekleri.

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

Uygulama başlatmak için kart kullanmaktan kaçının. Bunun yerine uygulama kısayolu veya standart 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 karo 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 oluşturup bildirmeniz gerekir.

Hızlı Ayarlar örneği, kutu oluşturma ve yönetme hakkında bir örnek sunar.

Özel simgenizi oluşturma

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

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

TileService'inizi oluşturma ve 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()
    }
}QuickSettingsTilesSnippets.kt

Uygulamanızın manifest dosyasında TileService beyan edin. TileService uygulamanızın adını ve etiketini (android:label için en fazla 18 karakter), önceki bölümde oluşturduğunuz özel simgeyi ve uygun izni ekleyin.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     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ğlama hizmetidir. TileService uygulamanız tarafından istendiğinde veya sistemin onunla iletişim kurması gerektiğinde bağlanır. Tipik bir bağlama hizmeti 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ğlama hizmeti 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ı 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 öğeniz her yeni yaşam döngüsü aşamasına 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 kullanıcı kartınızı kaldırıp tekrar eklediğinde çağrılır. Bu, tek seferlik başlatma işlemlerini gerçekleştirmek için en uygun zamandır. Ancak bu, gerekli tüm başlatma işlemlerini karşılamayabilir.

Not: onTileAdded(), kart her oluşturulduğunda çağrılmaz. Örneğin, cihaz kapatılmadan önce kart eklenmiş ve kaldırılmamışsa cihaz yeniden başlatıldığında veya açıldığında onTileAdded() çağrılmaz.
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() ve onStopListening() arasında bağlı kalır. Böylece uygulamanız, kartı değiştirebilir ve güncellemeleri gönderebilir.
onTileRemoved(): Bu yöntem yalnızca kullanıcı kartınızı kaldırdığında çağrılır.

Dinleme modu seçme

TileService cihazınız etkin modda veya etkin olmayan modda dinler. Uygulama manifestinde beyan etmeniz gereken etkin modu kullanmanızı öneririz. Aksi takdirde, TileService standart moddur ve bildirilmesi gerekmez.

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

Etkin mod (önerilir)

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

Kendi işlemi tarafından güncellenmesi gereken kart durumunuzla ilgili olarak TileService uygulamanız bildirim alıyorsa etkin modu kullanmanızı öneririz. Etkin kutular, Hızlı Ayarlar paneli kullanıcıya her gösterildiğinde bağlanmaları gerekmediğinden sistem üzerindeki yükü azaltır.

Dinleme durumunun başlatılmasını istemek ve onStartListening() için geri çağırma almak üzere 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ıya her gösterildiğinde bağlıysa TileService etkin olmayan moddadır. Bu, TileService öğenizin kontrolü dışında oluşturulup tekrar bağlanabileceği anlamına gelir. Ayrıca, kullanıcı kartı görüntülemediğinde bağlantısı kaldırılabilir ve yok edilebilir.

Kullanıcı, Hızlı Ayarlar panelini açtıktan sonra uygulamanız onStartListening() için bir geri çağırma 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 eklemeyin.

Kart durumlarına genel bakış

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

STATE_ACTIVE: Açık veya etkin durumunu gösterir. Kullanıcı bu durumdayken kartınızla etkileşim kurabilir.

Örneğin, kullanıcıların süreli bir antrenman oturumu başlatmasına olanak tanıyan bir fitness uygulaması kartında STATE_ACTIVE, 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 kartınızla etkileşim kurabilir.

Fitness uygulaması kartı örneğini tekrar kullanacak olursak STATE_INACTIVE durumundaki bir kart, kullanıcının antrenman seansı başlatmadığı ancak isterse başlatabileceği anlamına gelir.
STATE_UNAVAILABLE: Geçici olarak kullanılamayan bir durumu gösterir. Kullanıcı bu durumdayken kartınızla etkileşimde bulunamaz.

Örneğin, STATE_UNAVAILABLE durumundaki bir karo, şu anda bir nedenle kullanıcı tarafından kullanılamıyor demektir.

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

Sistem yalnızca Tile nesnenizin ilk durumunu ayarlar. Nesnenin durumunu, yaşam döngüsünün geri kalanı boyunca geçerli olacak şekilde ayarlarsınız.Tile

Sistem, Tile nesnenizin durumunu yansıtmak için kart simgesini ve arka planını renklendirebilir. Tile nesneleri STATE_ACTIVE olarak ayarlandığında en koyu renkte, STATE_INACTIVE ve STATE_UNAVAILABLE olarak ayarlandığında ise giderek daha açık renkte görünür. Tam renk tonu, üreticiye ve sürüme göre değişir.

VPN kutusu, nesne durumlarını yansıtacak şekilde renklendirildi — **Şekil 4.** Karo durumunu (sırasıyla etkin, etkin değil ve kullanılamıyor durumları) yansıtacak şekilde renklendirilmiş karo örnekleri.

Kartınızı güncelleme

onStartListening() numaralı telefondan geri arama aldığınızda kartınızı güncelleyebilirsiniz. Kartın moduna bağlı olarak kartınız, onStopListening() için geri çağırma alana kadar en az bir kez güncellenebilir.

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

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

Tile nesnesinin alanlarını doğru değerlere ayarladıktan sonra kartınızı güncellemek için updateTile() yöntemini çağırmanız gerekir. Bu işlem, sistemin güncellenen kart 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 = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}QuickSettingsTilesSnippets.kt

Dokunma işlemlerini işleme

Kartınız STATE_ACTIVE veya STATE_INACTIVE modundaysa kullanıcılar kartınıza dokunarak bir işlemi tetikleyebilir. Sistem daha sonra uygulamanızın onClick() geri çağırma işlevini çağırır.

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

var counter = 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()
}QuickSettingsTilesSnippets.kt

İletişim kutusu açma

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

Etkinlik başlatma

startActivityAndCollapse(), paneli daraltırken bir etkinlik başlatır. Etkinlikler, bir iletişim kutusunda gösterilebilecek olandan daha ayrıntılı bilgi varsa veya işleminiz yüksek düzeyde etkileşimliyse kullanışlıdır.

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

Bir karoya uzun dokunulduğunda kullanıcıya 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 bir <intent-filter> ekleyin.

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

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

Alternatif olarak, işareti belirli bir Activity bölümündeki AndroidManifest.xml içine ekleyebilirsiniz.

Kutunuzu açılıp kapatılabilir olarak işaretleme

Kartınız öncelikli olarak iki durumlu bir anahtar işlevi görüyorsa (kartların en yaygın davranışı budur) kartınızı açma/kapatma özellikli olarak işaretlemenizi öneririz. Bu sayede, işletim sistemine kartın davranışı hakkında bilgi sağlanır ve genel erişilebilirlik iyileştirilir.

Kutunuzu açılıp kapatı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>

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

Kartınız, kilitli cihazlarda kilit ekranının üstünde 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ştirmelidir.

Kilitliyken karo işlemini gerçekleştirmek güvenliyse kilit ekranının üstünde bir etkinlik başlatmak için startActivity() kullanın.

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

Kutu sınıflandırma

Hızlı Ayarlar'daki kullanıcı deneyimini iyileştirmek için kartınızı kategorilere ayırabilirsiniz. Sistem, kutuları Bağlantı, Ekran ve Gizlilik gibi kategoriler halinde düzenler. Sistem, Hızlı Ayarlar düzenleme modundaki kartları sıralamak ve gruplandırmak için bu kategorileri kullanır. Bu sayede kullanıcılar kartları daha kolay bulup yönetebilir.

Uygulama

TileService için bir kategori belirtmek istiyorsanız AndroidManifest.xml dosyasındaki hizmet beyanına bir meta veri alanı ekleyin:

AndroidManifest.xml dosyanızda, TileService için <service> öğesinin içine bir <meta-data> öğesi ekleyin.
android:name: Bu değeri android.service.quicksettings.TILE_CATEGORY olarak ayarlayın.
android:value: android.service.quicksettings.CATEGORY_CONNECTIVITY veya android.service.quicksettings.CATEGORY_DISPLAY gibi önceden tanımlanmış kategori sabitlerinden birini atayın.

Aşağıdaki örnekte gösterildiği gibi:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

API, aralarından seçim yapabileceğiniz önceden tanımlanmış bir kategori grubu sunar. Bu kategoriler, TileService sınıfında dize sabitleri olarak tanımlanır.

Kategori belirtilmezse sistem otomatik olarak varsayılan bir kategori atar:

Sistem uygulamalarından: Sistem uygulamasının parçası olan kartlar için.
Yüklediğiniz uygulamalardan: Kullanıcı tarafından yüklenen uygulamalardaki kartlar için.

Google Pixel cihazlar, Hızlı Ayarlar'da kategorileri kullansa da OEM'ler, kendi sistem kullanıcı arayüzlerinde bu kategori bilgilerini kullanabilir veya yok sayabilir.

Kullanıcıdan sen de paylaş kartınızı eklemesini isteme

Sen de paylaş kartınızı manuel olarak eklemek için kullanıcıların birkaç adımı uygulaması gerekir:

Hızlı Ayarlar panelini açmak için aşağı kaydırın.
Düzenle düğmesine dokunun.
Cihazlarındaki tüm kartlar arasında gezinerek kartınızı bulmalarını isteyin.
Kartınızı basılı tutup etkin kartlar listesine sürükleyin.

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

Android 13'ten itibaren, kullanıcıların kartınızı bir cihaza eklemesini çok daha kolay hale getirmek için requestAddTileService() yöntemini kullanabilirsiniz. Bu yöntem, kullanıcılardan kartınızı doğrudan Hızlı Ayarlar paneline hızlıca eklemelerini ister. İstemde uygulama adı, sağlanan etiket ve simge yer alır.

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

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

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

Kullanıcılardan ne zaman ve ne sıklıkta izin isteyeceğinize karar verirken dikkatli olun. requestAddTileService() yöntemini yalnızca bağlam içinde (ör. kullanıcı, kartınızın kolaylaştırdığı bir özellikle ilk kez etkileşime geçtiğinde) çağırmanızı öneririz.

Sistem, belirli bir ComponentName için istekleri işlemeyi durdurmayı seçebilir. Bu durum, isteklerin kullanıcı tarafından daha önce yeterli sayıda reddedilmesi halinde gerçekleşebilir. Kullanıcı, bu hizmeti almak için kullanılan Context ile belirlenir. Bu kimlik, mevcut kullanıcıyla eşleşmelidir.