Asistan bağlantıları

Doğrudan İşleminizin belirli bir amacına bağlantı veren bir URL oluşturabilirsiniz. Web veya mobil tarayıcıda Asistan bağlantısını (eski adıyla İşlem bağlantıları) tıklayan kullanıcılar cihazlarında Asistan'a yönlendirilir ve bu kullanıcılar İşleminizle doğrudan etkileşim kurar.

Asistan bağlantıları, kullanıcıyı Asistan dizinindeki İşleminizin sayfasına yönlendiren dizin web bağlantılarından farklıdır.

Asistan bağlantılarının yararlı olabileceği bazı durumlar aşağıda belirtilmiştir:

  • Kullanıcıları bir "nasıl yapılır" web sitesindeki sesli talimatlara yönlendirerek.
  • Bir yardım sayfasından kullanıcıları müşteri desteği deneyimine bağlama.
  • Gelecekteki güncellemelerinize dahil edebilmeleri için kullanıcıları bir güncelleme amacına bağlama.

Actions Console'da projenizden Asistan bağlantıları oluşturabilirsiniz. Asistan bağlantıları tüm dağıtım kanallarından (alfa, beta ve üretim) kullanılabilir. Örneğin, Asistan bağlantınız İşleminizin alfa sürümünde etkinleştirildiyse bağlantı, alfa test kullanıcıları tarafından kullanılabilir.

Bir İşlem için URL oluşturmak üzere aşağıdaki adımları uygulayın:

  1. Actions Console'da Dağıt > Asistan bağlantıları'na gidin.
  2. Intent (Niyet) için bağlantı oluşturmak istediğiniz amacı seçin.
  3. Intent_name için bağlantıyı etkinleştirmek ister misiniz? seçeneğini etkinleştirin.
  4. (isteğe bağlı) Kampanya parametreleri bölümünde, bağlantıya ek olarak URL parametreleri olarak yakalamak istediğiniz bilgileri girin.
  5. (isteğe bağlı) Bir Bağlantı başlığı girin. İşlemin ne yaptığını açıklamak için bu başlığı kullanın. Örneğin, İşleminiz kullanıcıyı konser bileti satın almak için işlem akışından ayırıyorsa bağlantı başlığınız "konser bileti satın alma" olabilir.

Bilgilerinizi girdikten sonra, Asistan bağlantısı için oluşturulan URL'yi veya kod snippet'ini görüntüleyebilir ve kopyalayabilirsiniz. Kullanıcıları bu İşlem'e yönlendirmek istediğiniz her yerde Asistan bağlantısını kullanın.

Herhangi bir amaç (ana veya özel, parametre içeren veya içermeyen) için Asistan bağlantılarını simülatör aracılığıyla veya bir cihazda test edebilirsiniz.

Asistan bağlantınızı bir cihazda test etmek için şu adımları uygulayın:

  1. Actions Console'da Asistan bağlantısını oluşturun.
  2. Asistan bağlantısını kendinize e-posta, sohbet mesajı veya başka bir biçimde URL olarak gönderin.
  3. Asistan özellikli bir cihazda, Actions projenizi oluşturmak için kullandığınız hesapla Asistan'da oturum açın.
  4. Aynı cihazda, kendinize gönderdiğiniz Asistan bağlantısını tıklayın.

Asistan bağlantısının beklendiği gibi çalıştığını onayladıktan sonra, bağlantıyı kullanıcılarınıza sunmak için İşleminizi yeniden dağıtmanız gerekir.

Asistan bağlantıları isteğe bağlı olarak URL'de amaç ve parametreler içerebilir. Kampanya parametrelerini eklemek için Kampanya parametreleri bölümünü kullanın.

Asistan bağlantısı başka parametre içermiyorsa Google Asistan aşağıdaki davranışla İşleminizin MAIN amacına (actions.intent.MAIN) bağlantı verir:

  • Asistan bağlantısında MAIN amacını açıkça etkinleştirmediyseniz Asistan, "app_name ile konuş" davranışına benzer şekilde ana amacı herhangi bir parametre olmadan eşleştirir.
  • MAIN amacını açık bir şekilde etkinleştirdiyseniz Asistan, parametreleri İşlemlerinize iletir.

Aşağıda, ek parametre olmadan MAIN amacını kullanan bir Asistan bağlantı URL'si örneği verilmiştir:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

Asistan bağlantısının URL'si için genel söz dizimi şöyledir:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

Ayarlayabileceğiniz URL parametreleri aşağıdaki tabloda açıklanmıştır:

URL parametresi Açıklama
$action_id İşlemin sayısal tanımlayıcısı.
$intent Yerleşik veya kullanıcı amacının tam adı.
$param İşlem paketinde belirtilen bir amaç parametresinin tam adı.
$value İşlem paketinde $param için bildirilen türün URL olarak kodlanmış değeri.
$utm_param Bir veya daha fazla UTM parametresi türünün listesi. Geçerli değerler şunları içerir: utm_source, utm_medium, utm_campaign, utm_term ve utm_content.
$utm_value UTM parametresinin dize değeri.

Asistan bağlantısı yerleşik intent içeriyorsa (Niyet, actions.intent. ile başlar) Google Asistan, URL'deki yerleşik amaç parametrelerini çıkarmaya çalışır ve bunları İşleminize aktarır. Asistan'ın yerleşik amaç parametresi olarak anlamadığı tüm parametreler kaldırılır.

Asistan, Conversational Actions'da bu parametreleri AppRequest mesajının bir parçası olarak karşılamanıza gönderir.

Aşağıdaki örnekte, tek bir intent parametresine sahip yerleşik intent içeren bir Asistan bağlantı URL'sini nasıl belirtebileceğiniz gösterilmektedir:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

Google Asistan, kullanıcı amaçları için yalnızca amacın bir parçası olarak İşleminiz tarafından tanımlanan parametreleri çıkarır ve diğer tüm parametreleri siler.

Aşağıdaki örnekte, kullanıcı niyeti içeren bir Asistan bağlantısı URL'sini nasıl belirtebileceğiniz gösterilmektedir:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

Yukarıdaki örnek URL için, Asistan AppRequest bölümüne aşağıdaki şekilde bir JSON nesnesi ekler:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

UTM parametreleri, kullanıcılar bir Asistan bağlantısını tıkladığında Google Asistan'ın İşleminize gönderdiği dizelerdir. Bu dizelerde yer alan bilgileri daha sonra analiz için kullanabilirsiniz.

Asistan'ın İşleminize gönderdiği UTM parametreleri şunları içerir:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

Aşağıdaki örnekte, UTM parametrelerini içeren bir Asistan bağlantısı URL'sini nasıl belirtebileceğiniz gösterilmektedir:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

Asistan, yukarıdaki örnek URL için AppRequest mesajına aşağıdaki bağımsız değişkenleri ekler:

argument {
  name: 'utm_source',
  raw_text: 'Google',
  text_value: 'Google',
}
argument {
  name: 'utm_medium',
  raw_text: 'email',
  text_value: 'email',
}
argument {
  name: 'utm_campaign',
  raw_text: 'holiday sale',
  text_value: 'holiday sale',
}

Zengin Asistan bağlantıları, Assistant.js kullanarak web siteniz aracılığıyla İşleminizin keşfedilmesini artırmanın bir yolunu sunar. Kullanıcılar hesap bağlama işlemini kullanarak İşleminizi deneyebilir ve Google hesaplarını hizmetinize bağlayabilir.

Bir kullanıcı web sitenizi ziyaret ettiğinde, Rich Asistan bağlantı akışını tetikleyen bir "Google Asistan ile Dene" düğmesi görür.

İşleminiz için hesap bağlamayı etkinleştirmek, kullanıcıların Asistan özellikli cihazlarında İşleminize erişmesine olanak tanır. Ayrıca kullanıcılar, hesaplarını hizmetinize Google Hesaplarına bağlayarak daha kişisel bir deneyim elde edebilir.

Hesap bağlamayla birlikte kullanıldığında Rich Asistan bağlantıları, Actions konsolundaki projenizde ayarlanan yetkilendirme URL'nizi kullanır. Daha fazla bilgi edinmek için hesap bağlama belgelerine bakın.

Ön koşullar

Rich Asistan bağlantılarını kullanmak için şunlara ihtiyacınız vardır:

Yerel geliştirme

Web sitenize zengin bir Asistan bağlantısı eklemek için aşağıdaki adımları tamamlayın:

  1. <PROJECT_ID> öğesini Actions proje kimliğinizle değiştirerek aşağıdaki JavaScript kitaplığını sayfanıza ekleyin:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
    </script>
    
  2. Aşağıdaki HTML etiketini sayfanızda bir yere ekleyin. Bu işlem, satır içi "Google Asistan ile deneyin" düğmesini yükler:

    <google-assistant-link-group>
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    

Proaktif tetikleme

Kullanıcılar sayfanızı ilk kez ziyaret ettiğinde zengin Asistan bağlantı akışının otomatik olarak başlamasını istiyorsanız <google-assistant-proactive-link> etiketini kullanın. Bu etiketi uyguladığınızda bağlantı, kullanıcılar ilk ziyaretlerinde satır içi düğmeyi seçmeden etkinleşir.

  1. Asistan bağlantı grubu etiketinize id ekleyin:

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
  2. Web sayfanıza bir <google-assistant-proactive-action-link> etiketi yerleştirin ve groupId özelliğini id olarak ayarlayın:

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
    <google-assistant-proactive-link
    groupId="my-group">
    </google-assistant-proactive-link>
    

Dağıtım

Zengin Asistan bağlantıları yalnızca sahibi olduğunuz ve Google ile doğruladığınız alanlarda çalışır. Yerel olarak geliştirme yapılırken, Actions projesine erişiminiz, Google Hesabınıza giriş yapmanız ve komut dosyası etiketinizde dev=true sorgu parametresini ayarlamanız bu gereksinimle atlanır.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

İşleminizi zengin Asistan bağlantılarıyla dağıtmak için:

  1. Actions konsolunda Dağıtma > Marka Doğrulama > Siteyi Bağla bölümünden herkese açık alanınızı kaydedin.
  2. dev=true sorgu parametresini komut dosyasından kaldırın:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
    </script>
    

Kısıtlamalar ve en iyi uygulamalar

Asistan bağlantı URL'nizin, dizinin veya diğer Google hizmetlerinin dışında dağıtılabilmesi ve referans verilebilmesi için aşağıdaki kısıtlamalar ve en iyi uygulamalar geçerlidir:

  • Tüm Asistan bağlantılarınızı desteklemeye devam edin. Daha sonra bozulan bir Asistan bağlantısı dağıtırsanız Actions projeniz sağlıksız olarak işaretlenip kaldırılabilir.
  • Bağlantı yayınlamak, güvenilmeyen kaynaklardan tetiklemeyi desteklediğiniz anlamına gelir. Bağlı İşlemler için, gerçek dünyada herhangi bir işlem yapmadan önce kullanıcıya açıkça onay vermeniz gerekir. Örneğin, akıllı ev cihazını kapatan bir İşlem, kullanıcıdan "$applianceName cihazını kapatmak istediğinizden emin misiniz?"

    Bu bağlamda gerçek dünyada yapılan işlemler; kullanıcının hizmetlerini, verilerini, cihazlarını, ağlarını, bilgisayarlarını veya API'lerini etkileyen herhangi bir eylemdir. Örneğin, e-posta gönderme, işlem gerçekleştirme, akıllı ev cihazının durumunu değiştirme, abonelik oluşturma veya bir içeriği güncelleme.