Uygulama İşlemleri ile Android uygulamasını Google Asistan'a genişletme (2. Seviye)

1. Genel Bakış

Uygulama İşlemleri, Android uygulamanızın erişimini genişletmenize yardımcı olmak için kullanıcıların Google Asistan'daki belirli uygulama özelliklerini doğrudan başlatmalarına olanak tanır. Android geliştiricisi olarak, Google Asistan'ın kullanıcılara sunulan işlevin türünü ve bu istekleri nasıl yerine getirmek istediğinizi bilmesini sağlayan özellikleri uygulayabilirsiniz.

İlk Uygulama İşlemleri codelab'inde, Health and Fitness BII kategorisindeki yerleşik amaçları (BII) uygulayarak Google Asistan'ı örnek bir fitness uygulamasına nasıl genişleteceğinizi öğrendiniz. BBI'ler, kullanıcıların Asistan'dan genellikle yapmasını istediği görev türlerini temsil eden kategoriler halinde düzenlenmiştir.

Anahtar terim: Asistan yerleşik intent veya kısaca BII, kullanıcının yapmak istediği belirli bir işlev türü için önceden tanımlanmış bir tetikleyicidir. Google, söz konusu belirli amaçla ilgili çok sayıda sorgu varyasyonunu anlamak için BBI'lere yönelik dil modelleri oluşturur ve bunları sürdürür.

Bu codelab'de, "Yaygın" bölümünden BII'leri kullanarak bir uygulamaya uygulama işlemleri eklemeyi öğreneceksiniz. BII kategorisi, neredeyse tüm Android uygulamalarının yerine getirebileceği yaygın uygulama görevlerini temsil eder.

Bu codelab'de, Uygulama İşlemleri ile uygulama geliştirmeyle ilgili orta düzey kavramlar ele alınmaktadır. Android uygulamaları geliştirme ve Android amaçlarının uygulanması konusunda daha önce deneyim sahibi olmanız gerekir.

Neler oluşturacaksınız?

Bu codelab'de, örnek bir Yapılacaklar listesi uygulamasına iki Yaygın BBI'yi ekleyerek kullanıcıların Asistan'dan şunları istemesini sağlayacaksınız:

• actions.intent.OPEN_APP_FEATURE BII ile uygulama içindeki özelliklere gidin.
• actions.intent.GET_THING BII ile uygulama içi aramayı kullanarak içerik arayın.

Not: Arama işlevi olan uygulamaların actions.intent.GET_THING BII'yi uygulaması gerekir. Uygulama İşlemleri dağıtım gereksinimleri hakkında daha fazla bilgi edinin.

Şekil 1. Google Asistan'ın bir uygulamada etkin görevleri gösterdiği üç aşamalı ekran.

Neler öğreneceksiniz?

Asistan'ı çoğu Android uygulamasını kapsayacak şekilde genişletmek için Genel kategori BBI'lerini nasıl kullanacağınızı öğreneceksiniz. Ayrıca, Android Studio için Google Asistan eklentisi ile Ortak BBI'leri nasıl test edeceğinizi de öğreneceksiniz.

Ön koşullar

• Git yüklü kabuk komutlarının çalıştırılacağı bir terminal.
• Android Studio'nun en son kararlı sürümü.
• İşlemlerinizi test etmek için Google Play Store'a internet erişimi olan fiziksel veya sanal bir Android cihaz.
• Test cihazınızdaki Android Studio'da ve hem Google uygulamasında hem de Google Asistan uygulamasında aynı Google Hesabınızla oturum açmış olmanız gerekir.

Not: Bu codelab'de açıklanan Uygulama İşlemleri'ni Google Asistan ile sınırlı sayıda yerel ayarda test edebilirsiniz. Yerel ayara göre hangi amaçların kullanılabileceğini öğrenmek için Yaygın BII referans belgelerine bakın.

Bu codelab'de, işlemlerinizi test etmek için bir Android cihaz (fiziksel veya sanal) kullanıyorsunuz. Fiziksel bir cihaz kullanıyorsanız cihazın yerel geliştirme makinenize bağlı olduğundan emin olun. Ayrıca, cihazdaki Google uygulamasında oturum açmış olmanız ve aynı Google Hesabı'nı kullanarak Android Studio'da oturum açmış olmanız gerekir. Ayrıca cihazda Google Asistan uygulaması da yüklü olmalıdır.

2. İşleyiş şeklini anlayın

Uygulama İşlemleri, Google Asistan'dan kullanıcıları Android uygulamanıza bağlar. Ama nasıl çalışırlar?

Kullanıcı, uygulamanızı kullanmak istediğini Asistan'a belirttiğinde Asistan, bir shortcuts.xml dosyasından uygulamanıza kaydedilen Uygulama İşlemlerini arar. Bu dosya, uygulamanın özelliklerini içeriyor. Bu özellikler, Asistan'ın yerleşik amacını veya özel amacını bir Android amacına veya derin bağlantısına bağlar.

Anahtar terim: Özellikler, kullanıcıların uygulamanızı başlatmak ve doğrudan belirli bir göreve atlamak için gerçekleştirebileceği işlem türlerini açıklamak üzere shortcuts.xml içinde tanımladığınız şablonlardır. Ayrıntılı bilgi için Özelliklerle ilgili Android dokümanlarına göz atın.

Kullanıcı, Asistan'a sorgu söylediğinde Asistan, kullanıcının girişini ayrıştırır ve bunu bir Uygulama İşlemleri niyetiyle eşleştirir (bu codelab'de bu bir BII olacaktır). Asistan, Android uygulamanızdaki shortcuts.xml dosyanızdan hangi özellikleri desteklediğinizi bilir. Amaç eşleştirmede, bu BII özelliği bu isteği nasıl yerine getirmek istediğinizi içerir. Bu codelab'de, istek karşılama, uygulamanızda bir etkinlik başlatan bir Android niyetidir.

Aşağıdaki şemada bu Asistan akışı gösterilmektedir:

Şekil 2. Google Asistan'ın sesli sorguları nasıl işlediğini açıklayan akış.

shortcuts.xml proje dosyası, her bir Uygulama İşlemi için aşağıdaki bilgileri içerir:

• Uygulama İşlemi'nin kullandığı yerleşik amaç veya özel amaç
• Kullanıcıya hangi Android etkinliği veya derin bağlantı sağlanmalıdır?
• Yerleşik intent parametreleri, kullanıcının Asistan'a sağladığı bilgilerle nasıl eşlenir?

Ardından Android etkinliğiniz, kullanıcıya istediği işlevselliği sağlamak için sağlanan Android niyetini veya derin bağlantısını filtreler ve işler. Sonuç olarak Asistan, kullanıcının sorgusuna yanıt olarak uygulamanızın işlevlerini çağırır.

3. Geliştirme ortamınızı hazırlama

Bu codelab'de, Android için Yapılacaklar listesi örnek uygulaması kullanılır. Bu örnek uygulama yapılacaklar listelerine öğe ekleyebilir, kategoriye göre öğe arayabilir ve tamamlanan görevlerle ilgili bilgileri görüntüleyebilir.

Temel dosyalarınızı indirin

Örnek uygulamanın GitHub deposunu klonlamak için aşağıdaki komutu çalıştırın:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

Kod deposunu klonladıktan sonra, Android Studio'da açmak için şu adımları uygulayın:

1. Android Studio'ya hoş geldiniz iletişim kutusunda Projeyi içe aktar'ı tıklayın.
2. Depoyu klonladığınız klasörü bulup seçin.

Tamamlanmış codelab'i temsil eden bir uygulama sürümünü görmek için --branch master işaretini kullanarak örnek uygulama deposunu klonlayın.

Android uygulama kimliğini güncelleme

Uygulamanın uygulama kimliğini güncellemek, test cihazınızda uygulamayı benzersiz bir şekilde tanımlar ve "Yinelenen paket adı"nı önler hatası oluşur. Uygulama kimliğini güncellemek için app/build.gradle dosyasını açın:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

Değiştir: "MYUNIQUENAME" applicationId alanına bunu benzersiz bir şekilde ekleyebilirsiniz.

Not: applicationId güncellendikten sonra "Gradle dosyaları son proje senkronizasyonundan bu yana değişti..." mesajını alırsınız. uyarısı gösterilir. Uygulamanızı yüklerken sorun yaşamamak için Şimdi Senkronize Et'i tıklayın.

Uygulamayı cihazınızda test etme

Uygulamada daha fazla değişiklik yapmadan önce, örnek uygulamanın neler yapabileceği hakkında bilgi sahibi olmanız faydalı olacaktır. Uygulamayı emülatörünüzde çalıştırmak için şu adımları izleyin:

1. Android Studio'da Çalıştır'ı > Uygulamayı çalıştırın veya araç çubuğunda Çalıştır'ı tıklayın.
2. Select Deployment Target (Dağıtım Hedefi Seçin) iletişim kutusunda bir cihaz seçip OK'i (Tamam) tıklayın. Önerilen işletim sistemi sürümü Android 10 (API düzeyi 30) veya sonraki sürümlerdir, ancak Actions on cihazlarda Android 5 (API düzeyi 21) sürümüne kadar da çalışır.
3. Asistan'ı kurmak ve çalıştığını doğrulamak için Ana sayfa düğmesine uzun basın. Henüz açmadıysanız cihazınızda Asistan'da oturum açmanız gerekir.

Android sanal cihazlar hakkında daha fazla bilgi için Sanal cihazları oluşturma ve yönetme başlıklı makaleyi inceleyin.

Şekil 3. Yapılacaklar listesi örnek uygulamasını gösteren animasyon.

Özelliklerini görmek için uygulamayı kısaca keşfedin. Artı simgesine dokunduğunuzda yeni bir görev öğesi oluşturulur, sağ üstteki menü öğeleri ise görev öğelerini tamamlanma durumuna göre aramanıza ve filtrelemenize olanak tanır.

Test eklentisini yükleyin

Google Asistan eklentisi, Uygulama İşlemlerinizi bir test cihazında test etmenize olanak tanır. Test aracınız yoksa aşağıdaki adımları uygulayarak aracı yükleyin:

1. Dosya > Ayarlar'ı (MacOS'te Android Studio > Tercihler) tıklayın.
2. Eklentiler bölümünde, Marketplace'e gidin ve "Google Assistant"ı arayın. Test aracını manuel olarak da indirip yükleyebilirsiniz.
   • Eklentiyi Marketplace'te bulamazsanız manuel olarak eklentiyi indirin ve Eklentiyi diskten yükleme başlıklı makaledeki talimatları uygulayın.
3. Aracı yükleyin ve Android Studio'yu yeniden başlatın.

Not: Test eklentisi, Android cihazınızdaki Google uygulaması üzerinden bilgileri Asistan'a gönderir.

4. Nesne Alma BII özelliğini ekleme

actions.intent.GET_THING BII, uygulama içi arama işlevinizi Google Asistan'ı da içerecek şekilde genişletir. Bu adımda GET_THING BII'yi uygulayıp test ederek kullanıcıların örnek uygulamada belirli görevleri aramasına olanak tanıyacaksınız.

İpucu: GET_THING BII, bir uygulamada varsayılan uygulama içi arama özelliğini kullanarak içerik veya varlık aramak için kullanılır. thing.name intent parametresini kullanarak arama ölçütlerini içerik veya varlık adıyla doldurun ve kullanıcıya en alakalı arama sonuçlarını sunun.

Nesne Alma özelliğini tanımlama

Asistan, aramayla ilgili bir Uygulama İşlemi sırasında kullanıcı sorgusundaki arama terimlerini thing.name BII parametresine ayıklar, ardından bu değeri Android uygulamasına iletir.

GET_THING BII'sini uygulamanıza eklemek için app/src/main/res/xml örnek proje dizininde bulunan shortcuts.xml öğesini, üst düzey <shortcuts> etiketinde bir <capability> öğesiyle güncelleyin:

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

Yukarıdaki yapılandırma:

1. Uygulamanın GET_THING BII'sine yanıt verdiğini beyan eder.
2. Söz konusu BII'ye yanıt olarak uygulamayı başlatan bir Android niyetinin nasıl oluşturulacağını belirtir.
   • Etkinlik, targetPackage ve targetClass kullanılarak tanımlanır.
   • thing.name BII parametresi, q adlı Extra Intent'e eşlenir.

Adlandırılmış etkinlik, uygulamanın manifest dosyasında mevcut olmalı ve dışa aktarılmalıdır.

Sağlanan Android uygulaması meta veriler içerdiğinden, AndroidManifest shortcuts.xml dosyasından haberdar olur:

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

Uygulama İşleminizi test etme

Uygulamanızla ilgili uygulama içi aramayı Asistan'dan test etmek için şu adımları uygulayın:

1. Android cihazınızın bağlı olduğundan emin olun.
2. Araçlar > Google Asistan > Uygulama İşlemleri Test Aracı'na göz atın.
3. Uygulama adı ve yerel ayar için varsayılan değerleri kabul etmek istiyorsanız Önizleme Oluştur'u tıklayın. Sizden istenirse Uygulama İşlemleri politikalarını ve hizmet şartlarını inceleyip kabul edin.
4. Aracın bir BII seçmeniz ve yapılandırmanız istediği ilk adımda actions.intent.GET_THING seçeneğini belirleyin. running shoes olan name değerini milk olarak değiştirin.
5. Run App Action'ı (Uygulama İşlemini Çalıştır) tıklayın.

Bu testte GET_THING BII, uygulamada "süt" içeren görevleri aramak için name özelliğini kullanıyor. Önceki Uygulama İşlemi'nde olduğu gibi, test aracını kullanarak işleminizi test edebilir veya test cihazınızda sadece "Ok Google, Görev Listesi'nde kek karışımını ara" ya da başka arama ifadeleri diyebilirsiniz.

İpucu: Test aracını çalıştırırken sorun yaşarsanız sorun giderme kılavuzunu inceleyin.

5. Uygulama açma özelliği BII özelliğini ekleme

Bu adımda, kullanıcıların Asistan'ı kullanarak etkin ve tamamlanmış görevlerini görüntülemelerine olanak tanıyan Uygulama açma özelliği BII'sini uygularsınız. Bunu yapmak için özelliğin nasıl tetiklendiği, parametrelerin nasıl iletildiği ve hangi Android amaçlarının çağrılacağı ile ilgili bilgileri içeren shortcuts.xml özelliğini tamamlayın. Bu codelab için OPEN_APP_FEATURE BII kullanacaksınız. Bu BII'yi uyguladıktan sonra işlemi cihazınızda test edersiniz.

Not: Bu BII, uygulamanın bir özelliğini başlatır. Bu amaç, kullanıcıların uygulamanızdaki bulması zor olabilecek veya birden fazla dokunuşla erişebilecek özelliklere gitmelerine yardımcı olmak için özellikle yararlıdır. Özellik parametresi için satır içi envanteri belirtmeniz gerekir.

Uygulama açma özelliğini ekleme

shortcuts.xml ürününde Uygulama Aç özelliği için, Öğe Alma Özelliğinin altına ikinci bir özellik ekleyin:

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

Bu özellik, Open app özelliği BII'sini ve Android amacını birlikte eşler. Böylece, uygulamayı açma özelliği tetiklendiğinde Android intent tetiklenir.

Desteklenen parametreler, Android amacını tetiklemeden önce kullanıcının girişinden alınır. OPEN_APP_FEATURE BII, kullanıcı sorgusundan çıkarılan uygulama özelliğini temsil eden bir parametreyi (feature) destekler. Bu uygulamanın destekleyeceği iki tür özellik vardır: Etkin Görev ve Tamamlanan Görev. Bu özellikler, kullanıcıların uygulamayı görev listelerinin filtrelenmiş bir görünümüyle açmasına olanak tanır. Bu özellikleri desteklemek için satır içi envanteri kullanmanız gerekir.

Anahtar terim: Satır içi envanter, uygulamanın anladığı bir varlık grubunu, satır içi envanteri destekleyen bir BII parametresine sağlayarak BBI'ler için öğe ayıklama işlemine rehberlik eder. Ayrıntılar için Uygulama İşlemleri için satır içi envanter bölümüne bakın.

Satır içi envanter kullanarak intent parametrelerini yönetme

Intent parametreleri, kullanıcı sorgusundan çıkarılan öğeleri temsil eder. Örneğin, bir kullanıcı "Ok Google, ExampleApp'ten pizza sipariş et" gibi bir şey söylerse Asistan "pizza" kelimesini ayıklar bir food.item schema.org intent parametresine ekler ve parametreyi, işlenecek işleminize iletir.

Open uygulama özelliği BII, kullanıcı sorgusundan çıkarılan uygulama özelliğini temsil eden bir parametreyi (feature) destekler. Bu parametre için bir satır içi envanter gerekir. Bu envanter, Asistan'a parametre değerinin eşleştirileceği bir dizi desteklenen uygulama özelliği adı sağlar.

feature intent parametresini işlemek için, "Uygulama açma özelliği" özelliğinin üzerinde aşağıdaki kodla shortcuts.xml cihazınıza kısayol ekleyin:

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

Yukarıdaki kodda, özellik ve parametre bağlamaları olan shortcut öğeleri olarak temsil edilen bir satır içi envanter tanımladınız. Kısayollar, BII parametreleri için envanter olarak kullanılabilir. Google Asistan, kullanıcı sorgusunu Kısayolların parametre bağlamasındaki değerlerle eşleştirir. Eşleşen parametre değeri için shortcutId, sipariş karşılama amacına eklenir. Kullanıcı, bir istekle OPEN_APP_FEATURE BII'yi etkinleştirdiğinde Asistan, özellik parametresi değerini bir kısayolun değer özelliğiyle eşleştirir ve değeri Extra içindeki targetClass öğesine parameter olarak iletir.

Örneğin, kullanıcı "Ok Google, exampleApp'te tamamlanmış görevlerimi göster" gibi bir şey derse Asistan, "tamamlanan görevler" özellik amacı parametresinin değerini, ilgili envanter kısayoluyla eşleştirir ve bu değer OPEN_APP_FEATURE özelliğine iletir. Asistan, ardından Android niyetini tetikler.

Uygulama İşleminizi test etme

Geliştirme ve test sırasında, bir test cihazında Asistan uygulama İşleminizi önizlemek için Google Asistan eklentisini kullanırsınız. Aracı, bir Uygulama İşlemi'nin intent parametrelerini ayarlamak için de kullanabilirsiniz. Böylece, kullanıcıların Asistan'dan işlem yapmasını isteyebilecekleri çeşitli yöntemlerin eylemlerinin nasıl işlendiğini test edebilirsiniz.

Uygulama İşleminizi test aracıyla test etmek için aşağıdaki adımları izleyin:

1. Fiziksel Android test cihazınızı bağlayın veya Android emülatörünüzü başlatın
2. Test aracı görünmüyorsa, Araçlar > Google Asistan > Uygulama İşlemleri Test Aracı'na göz atın.
3. Önizlemenizi yenilemek için Güncelle düğmesini tıklayın.
4. Aracın bir BII seçmeniz ve yapılandırmanız istediği ilk adımda actions.intent.OPEN_APP_FEATURE seçeneğini belirleyin.
5. Özellik kutusunda, varsayılan History değerini Completed tasks ile güncelleyin.
6. Run App Action'ı (Uygulama İşlemini Çalıştır) tıklayın.

İpucu: Test aracını çalıştırırken sorun yaşarsanız sorun giderme kılavuzunu inceleyin.

Alternatif olarak, uygulama işleminizi denemek için doğrudan cihazınızdaki Asistan uygulamasında çağrı adını kullanabilirsiniz. Örneğin, "Ok Google, tamamlanmış görevleri Görev Listesi'nde göster" diyebilirsiniz.

6. Sonraki adımlar

Tebrikler!

Artık yaygın BBI'leri kullanarak hemen hemen tüm Android uygulamalarının Google Asistan ile çalışmasını sağlayabilirsiniz.

İşlediklerimiz

Bu codelab'de şunları öğrendiniz:

• Kullanıcıların Asistan'ı kullanarak belirli uygulama özelliklerini ayrıntılı olarak incelemesini sağlama.
• Kullanıcılar Asistan'dan uygulama içi aramaya nasıl erişebilir?
• Google Asistan Eklentisi'ni kullanarak genel BBI'leri test etme.

Sırada ne var?

Buradan Yapılacaklar listesi uygulamanızda daha fazla ayrıntılandırma deneyebilirsiniz. Bitmiş projeye referans vermek için GitHub'da depo –master dal bölümünü inceleyin.

Aşağıda, Uygulama İşlemleri ile bu uygulamanın kapsamını genişletme hakkında daha fazla bilgi için bazı öneriler verilmiştir:

• Uygulama İşlemlerinizin performansını nasıl izleyeceğinizi öğrenmek için Firebase için Google Analytics ile yapılacaklar listesi örneğini inceleyin.
• Uygulamalarınızı Asistan'a genişletmenin diğer yollarını keşfetmek için Uygulama İşlemleri yerleşik intentler referansını ziyaret edin.

Actions on Google yolculuğunuza devam etmek için aşağıdaki kaynakları inceleyin:

• developers.google.com/assistant: Actions on Google için resmi belge sitesi.
• Uygulama İşlemleri örnek dizini: Uygulama İşlemleri özelliklerini keşfetmek için örnek uygulamalar ve kod.
• Actions on Google GitHub deposu: Örnek kod ve kitaplıklar.
• r/GoogleAssistantDev: Google Asistan ile çalışan geliştiriciler için resmi Reddit topluluğu.

En son duyurularımızı kaçırmamak için bizi Twitter @ActionsOnGoogle'da takip edin ve çalışmalarınızı paylaşmak için #AoGDevs'e tweet atın.

Geri bildirim anketi

Son olarak, bu codelab'deki deneyiminiz hakkında geri bildirimde bulunmak için lütfen bu anketi doldurun.