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

1. Genel Bakış

Uygulama İşlemleri, kullanıcıların Google Asistan'dan doğrudan belirli uygulama özelliklerini başlatmasına olanak tanıyarak Android uygulamanızın erişim alanını genişletmenize yardımcı olur. Android geliştiricisi olarak, Google Asistan'ın kullanıcılara sunulan işlev türünü ve bu istekleri nasıl karşılamak istediğinizi bilmesini sağlayan özellikleri uygulayabilirsiniz.

İlk uygulama işlemleri codelab'inde, Sağlık ve Fitness BII kategorisindeki yerleşik amaçları (BII) uygulayarak Google Asistan'ı örnek bir fitness uygulamasına nasıl genişleteceğinizi öğrendiniz. Kullanıcıların Asistan'dan yapmasını istediği görev türlerini temsil eden kategorilerde BII'ler düzenlenir.

Önemli terim: Asistan'da yerleşik amaç (kısaca BII), kullanıcının yapmak istediği belirli bir işlev türü için önceden tanımlanmış bir tetikleyicidir. Google, bu amaçla ilgili çok çeşitli sorguları anlamak için BII'lerin dil modellerini oluşturur ve bunları korur.

Bu codelab'de, "Common" BII kategorisindeki BII'leri kullanarak bir uygulamaya uygulama işlemleri eklemeyi öğreneceksiniz. Bu kategori, neredeyse tüm Android uygulamalarının gerçekleştirebileceği yaygın uygulama görevlerini temsil eder.

Bu codelab'de, uygulama işlemleriyle geliştirme yapmaya yönelik orta düzey kavramlar ele alınmaktadır. Daha önce Android uygulamaları geliştirme ve Android amaçlarını uygulama deneyiminiz olmalıdır.

Ne oluşturacaksınız?

Bu codelab'de, örnek bir yapılacaklar listesi uygulamasına iki Common BIIs ekleyerek kullanıcıların Asistan'dan şunları yapmasını 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 arama

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

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

Neler öğreneceksiniz?

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

Ön koşullar

• Git'in yüklü olduğu kabuk komutlarını çalıştırmak için 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.
• Aynı Google Hesabınızla Android Studio'da oturum açmış olmanız ve test cihazınızda hem Google uygulamasının hem de Google Asistan uygulamasının yüklü olması gerekir.

Not: Bu codelab'de açıklanan uygulama işlemleri, Google Asistan ile sınırlı sayıda yerel ayarda test edilebilir. Yerel ayara göre hangi amaçların kullanılabildiğini öğrenmek için Common BII referans dokümanlarına bakın.

Bu codelab'de, işlemlerinizi test etmek için bir Android cihaz (fiziksel veya sanal) kullanırsınız. 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ış ve aynı Google Hesabı'nı kullanarak Android Studio'da oturum açmış olmanız gerekir. Cihazda Google Asistan uygulaması da yüklü olmalıdır.

2. İşleyiş şeklini anlama

Uygulama İşlemleri, Google Asistan'daki kullanıcıları Android uygulamanıza bağlar. Peki bu işlemler nasıl çalışır?

Kullanıcı Asistan'a uygulamanızı kullanmak istediğini belirttiğinde Asistan, shortcuts.xml dosyasından uygulamanıza kayıtlı uygulama işlemleri arar. Bu dosya, uygulamanın özelliklerini içerir. Bu özellikler, Asistan'da yerleşik bir amacı veya özel bir amacı Android amacına ya da derin bağlantıya bağlar.

Önemli terim: Yetenekler, kullanıcıların uygulamanızı başlatmak ve doğrudan belirli bir göreve geçmek için gerçekleştirebileceği işlem türlerini bildirmek üzere shortcuts.xml içinde tanımladığınız şablonlardır. Ayrıntılar için Android'deki özelliklerle ilgili dokümanlara bakın.

Kullanıcı Asistan'a bir sorgu söylediğinde Asistan, kullanıcının girişini ayrıştırır ve bir Uygulama İşlemi niyetiyle (bu codelab'de BII) eşleştirir. Asistan, Android uygulamanızdaki shortcuts.xml dosyanızdan hangi özellikleri desteklediğinizi bilir. Niyet eşleşmesiyle birlikte, bu BII'ye sahip özellik, isteği nasıl yerine getirmek istediğinizi içerir. Bu codelab'de karşılama, uygulamanızda bir etkinlik başlatan bir Android intent'idir.

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

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

shortcuts.xml proje dosyası, her uygulama iş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 amaçla ilgili parametrelerin, kullanıcı tarafından Asistan'a sağlanan bilgilerle nasıl eşlendiği

Android etkinliğiniz daha sonra, kullanıcıya istediği işlevi sağlamak için sağlanan Android amacını veya derin bağlantıyı filtreleyip işler. Sonuç olarak, Asistan'ın kullanıcının sorgusuna yanıt olarak uygulama işlevinizi çağırdığı bir kullanıcı deneyimi elde edilir.

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, öğeleri kategoriye göre arayabilir ve tamamlanan görevlerle ilgili bilgileri görüntüleyebilir.

Temel dosyalarınızı indirme

Ö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

Depoyu klonladıktan sonra Android Studio'da açmak için aşağıdaki adımları uygulayın:

1. Welcome to Android Studio (Android Studio'ya Hoş Geldiniz) iletişim kutusunda Import project'i (Projeyi içe aktar) tıklayın.
2. Depoyu klonladığınız klasörü bulup seçin.

Tamamlanmış codelab'i temsil eden 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, uygulamayı test cihazınızda benzersiz bir şekilde tanımlar ve uygulama Play Console'a yüklenirse "Paket adı yineleniyor" hatasını önler. Uygulama kimliğini güncellemek için app/build.gradle uygulamasını açın:

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

applicationId alanındaki "MYUNIQUENAME" ifadesini size özel benzersiz bir ifadeyle değiştirin.

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

Uygulamayı cihazınızda test etme

Uygulamada başka değişiklikler yapmadan önce örnek uygulamanın neler yapabileceği hakkında fikir edinmek faydalı olur. Uygulamayı emülatörünüzde çalıştırmak için aşağıdaki adımları uygulayın:

1. Android Studio'da Run (Çalıştır) > Run app (Uygulamayı çalıştır) seçeneğini belirleyin veya araç çubuğunda Run'ı (Çalıştır) tıklayın.
2. Select Deployment Target (Dağıtım Hedefi Seçin) iletişim kutusunda bir cihaz seçin ve OK'u (Tamam) tıklayın. İşlemler Android 5 (API düzeyi 21)'ten itibaren tüm cihazlarda çalışsa da önerilen OS sürümü Android 10 (API düzeyi 30) veya sonraki sürümlerdir.
3. Asistan'ı kurmak ve çalıştığını doğrulamak için Ana Sayfa düğmesine uzun basın. Henüz yapmadıysanız cihazınızda Asistan'da oturum açmanız gerekir.

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

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

Uygulamanın neler yapabileceğini görmek için kısa bir keşfe çıkın. Artı simgesine dokunarak yeni bir görev öğesi oluşturabilir, sağ üstteki menü öğelerini kullanarak da görev öğelerini tamamlanma durumuna göre arayabilir ve filtreleyebilirsiniz.

Test eklentisini yükleyin

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

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

Not: Test eklentisi, Android cihazınızdaki Google uygulaması aracılığıyla Asistan'a bilgi gönderir.

4. Get Thing BII özelliğini ekleme

actions.intent.GET_THING BII, uygulama içi arama işlevinizi Google Asistan'a genişletir. Bu adımda, GET_THING BII'yi uygulayıp test ederek kullanıcıların örnek uygulamada belirli görevleri aramasını sağlayacaksınız.

İpucu: GET_THING BII, bir uygulamadaki varsayılan uygulama içi arama özelliği kullanılarak içerik veya öğe aramak için kullanılır. thing.name amaç parametresini kullanarak arama ölçütlerini içerik veya öğe adıyla doldurun ve kullanıcıya en alakalı arama sonuçlarını gösterin.

Nesne alma özelliğini tanımlama

Aramayla ilgili bir uygulama işlemi sırasında Asistan, arama terimlerini kullanıcı sorgusundan thing.name BII parametresine çıkarır ve bu değeri Android uygulamasına iletir.

Uygulamanıza GET_THING BII'sini eklemek için app/src/main/res/xml örnek proje dizininde bulunan shortcuts.xml dosyasını, üst düzey <shortcuts> etiketi içinde 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'ye yanıt verdiğini beyan eder.
2. Bu BII'ye yanıt olarak uygulamayı başlatan bir Android niyeti oluşturma şeklini belirtir.
   • Etkinlik, targetPackage ve targetClass kullanılarak tanımlanır.
   • BII parametresi thing.name, q adlı Amaç Ekstrası'na eşlenir.

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

Sağlanan Android uygulamasında meta veriler bulunduğundan AndroidManifest, shortcuts.xml dosyasının farkındadır:

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

Uygulama İşleminizi test etme

Uygulamanızda uygulama içi aramayı Asistan'dan test etmek için aşağıdaki 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 gidin.
3. Uygulama adı ve yerel ayar için varsayılan değerleri kabul etmek üzere Önizleme Oluştur'u tıklayın. İstenirse Uygulama İşlemleri politikalarını ve hizmet şartlarını inceleyip kabul edin.
4. Aracın sizden bir BII seçip yapılandırmanızı istediği ilk adımda actions.intent.GET_THING simgesini seçin. name değerini running shoes yerine milk olarak değiştirin.
5. 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 işleminde olduğu gibi, test aracını kullanarak veya test cihazınızda "Ok Google, Görev Listesi'nde kek karışımı ara" gibi arama ifadeleri söyleyerek işleminizi test edebilirsiniz.

İpucu: Test aracını çalıştırırken sorun yaşarsanız sorun giderme kılavuzuna göz atın.

5. Open app feature BII özelliğini ekleyin

Bu adımda, kullanıcıların Asistan'ı kullanarak etkin ve tamamlanmış görevlerini görüntülemesini sağlayan Open app feature BII'yi (Uygulama açma özelliği BII) uygularsınız. Bunu yapmak için shortcuts.xml bölümündeki özelliği tamamlayın. Bu bölümde, özelliğin nasıl tetiklendiği, parametrelerin nasıl iletildiği ve hangi Android amaçlarının çağrılacağı hakkında bilgiler yer alır. Bu codelab'de OPEN_APP_FEATURE BII'yi kullanacaksınız. Bu BII'yi uyguladıktan sonra cihazınızda işlemi test edersiniz.

Not: Bu BII, uygulamanın bir özelliğini başlatır. Bu amaç, özellikle kullanıcıların uygulamanızda aksi takdirde bulunması zor olabilecek veya erişmek için birden fazla dokunma gerektirebilecek özelliklere gitmesine yardımcı olmak için kullanışlıdır. Özellik parametresi için satır içi envanter belirtmeniz gerekir.

Uygulamayı açma özelliği ekleme

shortcuts.xml içindeki Uygulamayı aç özelliği için Get Thing Capability öğesinin 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 feature BII ve Android intent'i birlikte eşler. Böylece, Open app feature tetiklendiğinde Android intent de tetiklenir.

Android amacını tetiklemeden önce, desteklenen parametreler kullanıcının girişinden alınır. OPEN_APP_FEATURE BII, kullanıcı sorgusundan çıkarılan uygulama özelliğini temsil eden feature parametresini destekler. Bu uygulamanın destekleyeceği iki tür özellik vardır: Etkin Görev ve Tamamlanmış Görev. Bu özellikler, kullanıcıların görev listelerini filtreleyerek uygulamayı açmalarına olanak tanır. Bu özellikleri desteklemek için satır içi envanter kullanmanız gerekir.

Anahtar terim: Satır içi envanter, bir uygulamanın anladığı bir dizi öğeyi satır içi envanteri destekleyen bir BII parametresine sağlayarak BII'ler için satır içi envanter kılavuzlu öğe ayıklama işlemi gerçekleştirir. Ayrıntılar için Uygulama İşlemleri için satır içi envanter başlıklı makaleyi inceleyin.

Satır içi envanter kullanarak intent parametrelerini işleme

Amaç 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öylediğinde Asistan, "pizza"yı food.item schema.org amaç parametresine ayıklar ve parametreyi işlenmesi için işleminize iletir.

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

feature intent parametresini işlemek için shortcuts.xml işlevinize, Uygulamayı açma özelliği yeteneğinin üstüne aşağıdaki kodu ekleyerek bir 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, yetenek ve parametre bağlamaları içeren shortcut öğeleri olarak gösterilen 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 bir parametre değeri için karşılama amacına shortcutId eklenir. Bir kullanıcı, istekte bulunarak 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çinde parameter olarak targetClass'ye iletir.

Örneğin, bir kullanıcı "Ok Google, ExampleApp'te tamamlanan görevlerimi göster" gibi bir şey söylerse Asistan, "tamamlanan görevler" olan özellik amacının parametre değerini, bu değeri OPEN_APP_FEATURE özelliğine ileten ilgili envanter kısayoluyla eşleştirir. Ardından Asistan, Android amacını tetikler.

Uygulama İşleminizi test etme

Geliştirme ve test sırasında, test cihazında Asistan ile uygulama işleminizin önizlemesini yapmak için Google Asistan eklentisini kullanırsınız. Ayrıca, bir uygulama işleminin amaç parametrelerini ayarlamak için de bu aracı kullanabilirsiniz. Böylece, işleminizin, kullanıcının Asistan'dan işlemi çalıştırmasını isteyebileceği çeşitli yöntemleri nasıl ele aldığını test edebilirsiniz.

Test aracını kullanarak uygulama işleminizi test etmek için aşağıdaki adımları uygulayın:

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 giderek açın.
3. Önizlemenizi yenilemek için Güncelle düğmesini tıklayın.
4. Aracın sizden bir BII seçip yapılandırmanızı istediği ilk adımda actions.intent.OPEN_APP_FEATURE simgesini seçin.
5. Özellik kutusunda, varsayılan History değerini Completed tasks ile güncelleyin.
6. Uygulama İşlemini Çalıştır'ı tıklayın.

İpucu: Test aracını çalıştırırken sorun yaşarsanız sorun giderme kılavuzuna göz atın.

Alternatif olarak, uygulama işleminizi denemek için doğrudan cihazınızdaki Asistan uygulamasında çağırma adını kullanabilirsiniz. Örneğin, "Ok Google, görev listesinde tamamlanan görevleri göster" diyebilirsiniz.

6. Sonraki adımlar

Tebrikler!

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

İşlediğimiz konular

Bu codelab'de şunları öğrendiniz:

• Kullanıcıların Asistan'ı kullanarak belirli uygulama özelliklerine ayrıntılı bir şekilde göz atmasına izin verme
• Kullanıcılar, Asistan'dan uygulama içi aramaya nasıl erişebilir?
• Google Asistan eklentisini kullanarak yaygın BII'leri test etme

Sırada ne var?

Buradan, yapılacaklar listesi uygulamanızda daha fazla iyileştirme yapmayı deneyebilirsiniz. Tamamlanmış projeye referans vermek için GitHub'daki –master branch deposuna bakın.

Bu uygulamayı Uygulama İşlemleri ile genişletme hakkında daha fazla bilgi edinmek için aşağıdaki önerilerden yararlanabilirsiniz:

• Uygulama İşlemlerinizin performansını nasıl izleyeceğinizi öğrenmek için Firebase için Google Analytics ile yapılacaklar listesi örneğini inceleyin.
• Uygulama İşlemleri yerleşik amaç referansı sayfasını ziyaret ederek uygulamalarınızı Asistan'a entegre etmenin diğer yollarını keşfedin.

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

• developers.google.com/assistant: Actions on Google için resmi doküman sitesi.
• Uygulama İşlemleri örnek dizini: Uygulama İşlemleri özelliklerini keşfetmek için örnek uygulamalar ve kodlar.
• 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ızdan haberdar olmak için Twitter'da @ActionsOnGoogle hesabımızı takip edin ve geliştirdiklerinizi paylaşmak için #AoGDevs etiketini kullanarak tweet atın.

Geri bildirim anketi

Son olarak, bu codelab ile ilgili deneyiminizi paylaşmak için lütfen bu anketi doldurun.