Ana sayfalar

Ana sayfalar, bir veya daha fazla bağlam dışı kart tanımlama olanağı sağlayan bir Google Workspace eklentisi özelliğidir. Bağlam dışı kartlar, kullanıcı belirli bir bağlamın dışındayken (ör. açık bir ileti veya taslak olmadan Gmail gelen kutusunu görüntülerken) kullanıcı arayüzü gösterir.

Ana sayfalar, hızlı erişim yan panelindeki Google uygulamalarına (Google Keep, Google Takvim ve Google Görevler) benzer şekilde bağlam dışı içerik göstermenize olanak tanır. Ana sayfalar, kullanıcılar eklentinizi ilk kez açtığında başlangıç noktası olarak da kullanılabilir ve yeni kullanıcılara eklentinizle nasıl etkileşim kuracaklarını öğretmek için faydalıdır.

Proje manifestinizde belirterek ve bir veya daha fazla homepageTrigger işlevi uygulayarak eklentiniz için bir ana sayfa tanımlayın (bkz. Ana sayfa yapılandırması). Eklentiniz Google Chat'i genişletiyorsa ana sayfası, Chat uygulamasıyla bire bir doğrudan mesajın Ana Sayfa sekmesinde görünür ve manifest yerine Google Cloud Console'da yapılandırılır (bkz. Chat için ana sayfa yapılandırma).

Eklentinizin genişlettiği her ana makine uygulaması için bir tane olmak üzere birden fazla ana sayfanız olabilir. Ayrıca, özel bir ana sayfa belirtmediğiniz ana makinelerde kullanılan tek bir ortak varsayılan ana sayfa da tanımlayabilirsiniz.

Eklenti ana sayfanız şu durumlarda gösterilir:

  • Eklenti, ana makinede ilk kez açıldığında (yetkilendirmeden sonra) veya kullanıcı, Chat'te Chat uygulamanızla bire bir doğrudan mesajlaşmada Ana Sayfa sekmesini açtığında.
  • Kullanıcı, eklenti açıkken bağlamsal bir bağlamdan bağlamsal olmayan bir bağlama geçtiğinde. Örneğin, Takvim etkinliğini ana Takvim'de düzenleme.
  • Kullanıcı, geri düğmesini diğer tüm kartları dahili yığınlardan çıkaracak kadar çok tıkladığında.
  • Bağlam dışı bir karttaki kullanıcı arayüzü etkileşimi Navigation.popToRoot çağrısına neden olduğunda.

Ana sayfa tasarlamanız önerilir. Herhangi bir kart tanımlamazsanız kullanıcı ana sayfaya her gittiğinde eklentinizin adını içeren genel bir kart kullanılır.

Ana sayfa yapılandırması

Google Workspace eklentileri, addOns.common.homepageTrigger alanını kullanarak eklenti manifestindeki ana makine uygulamaları için varsayılan ana sayfa (bağlam dışı) eklenti içeriğini yapılandırır:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • runFunction: Google Workspace eklenti çerçevesinin, ana sayfa eklenti kartlarını oluşturmak için çağırdığı Google Apps Komut Dosyası işlevinin adı. Bu işlev, ana sayfa tetikleme işlevidir. Bu işlev, ana sayfa kullanıcı arayüzünü oluşturan Card nesnelerinden oluşan bir dizi oluşturup döndürmelidir. Birden fazla kart döndürülürse ana makine uygulaması, kart başlıklarını kullanıcının seçebileceği bir listede gösterir (bkz. Birden fazla kart döndürme).

  • enabled: Bu kapsam için ana sayfa kartlarının etkinleştirilip etkinleştirilmeyeceği. Bu alan isteğe bağlıdır ve varsayılan olarak true değerini alır. Bu ayarın false olarak belirlenmesi, ana sayfa kartlarının tüm ana makinelerde devre dışı bırakılmasına neden olur (söz konusu ana makine için geçersiz kılınmadığı sürece; ana makineye özgü yapılandırmaya bakın).

Bir barındırıcının ortak ana sayfayı kullanabilmesi için hem addOns.common.homepageTrigger hem de barındırıcının üst düzey kaynağı, eklenti manifest dosyasında bulunmalıdır. Örneğin, manifestte addOns.gmail yoksa eklenti Gmail için devre dışı bırakılır ve bu ana makinede ana sayfa veya başka bir işlev gösterilmez.

Ortak yapılandırmaya ek olarak, her ana makine uygulamasının yapılandırmasında, addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger ve diğer ana makineye özel tetikleyicilerde, ana makine başına aynı şekilde yapılandırılmış geçersiz kılmalar da mevcuttur.

Aşağıdaki örnekte, ortak bir ana sayfa tetikleyicisinin tanımlandığı ancak Takvim ve Drive için özel işlevlerle geçersiz kılındığı ve Gmail için devre dışı bırakıldığı bir manifest gösterilmektedir. Bu yapılandırmada, ortak buildHomePage işlevi hiçbir zaman yürütülmez. Bunun nedeni, işlevin geçersiz kılınması veya ana makinenin devre dışı bırakılmasıdır.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

Aşağıdaki manifest alıntısı, varsayılan homepageTrigger ve Gmail yapılandırması atlanmış olsa da önceki örnekle eşdeğerdir:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

homepageTrigger bölümlerinin hiçbiri zorunlu değildir. Bir ana üründeki eklenti için gösterilen kullanıcı arayüzü, ilgili manifest alanının varlığına ve ilişkili bir homepageTrigger olup olmadığına bağlıdır. Aşağıdaki örnekte, farklı manifest yapılandırmaları için bir ana sayfa kullanıcı arayüzü oluşturmak üzere hangi eklenti tetikleyici işlevlerinin yürütüldüğü gösterilmektedir:

Eklenti ana sayfası tetikleyici işlevinin yürütme akışını gösteren şema

Chat için ana sayfa yapılandırma

Chat'i genişleten eklentiler, diğer Google Workspace ana uygulamalarının aksine sağ taraftaki hızlı erişim panelinde ana sayfa göstermez ve manifest dosyasında addOns.common.homepageTrigger kullanmaz. Bunun yerine Chat, ana sayfanızı Chat uygulamasıyla bire bir doğrudan mesajın Ana Sayfa sekmesinde kart olarak gösterir.

Google Cloud Console'da Chat eklentiniz için bir uygulama ana sayfası tetikleyicisini etkinleştirmek ve yapılandırmak üzere:

  1. Google Cloud Console'da Menü > API'ler ve Hizmetler > Etkin API'ler ve hizmetler > Google Chat API > Yapılandırma'ya gidin.

    Google Chat API Yapılandırması'na gitme

  2. Etkileşimli özellikler bölümünde Etkileşimli özellikleri etkinleştir'in açık olduğundan emin olun ve Destek Uygulaması Ana Sayfası onay kutusunu işaretleyin.

  3. Bağlantı ayarları > Tetikleyiciler bölümünde, eklenti mimarinize göre Uygulama ana sayfası alanında uygulama ana sayfası işleyicinizi belirtin:

    • HTTP: Uygulama Ana Sayfası isteklerini işleyen HTTPS uç noktası URL'sini girin (veya ortak HTTP uç noktası URL'nizin tüm etkinlikleri alması için boş bırakın).
    • Google Apps Komut Dosyası: Ana sayfa kartınızı oluşturan ve döndüren Google Apps Komut Dosyası geri çağırma işlevinin adını girin (varsayılan olarak onAppHome).

  4. Kaydet'i tıklayın.

Bir kullanıcı, Chat uygulamanızla doğrudan mesajın Ana Sayfa sekmesini açtığında Chat, uç noktanıza veya işlevinize bir App Home tetikleyici etkinliği gönderir. Ana sayfayı oluşturmak için pushCard gezinme işlemi içeren bir RenderActions nesnesi döndürün (veya ana sayfa kartındaki bir düğmeyi tıklamaya yanıt olarak ana sayfayı güncellerken updateCard kullanın):

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Komut Dosyası

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Chat tetikleyicilerini işleme ve işlemleri döndürme hakkında daha fazla bilgi için Kullanıcı etkileşimlerini alma ve yanıtlama başlıklı makaleyi inceleyin.

Ana sayfa etkinlik nesneleri

Çağrıldığında, daha önce açıklanan ana sayfa tetikleyici işlevi (runFunction) veya uygulama ana sayfası uç noktasına, çağırma bağlamındaki verileri içeren bir etkinlik nesnesi iletilir.

Ana sayfa etkinlik nesneleri, widget veya bağlamsal bilgiler içermiyor. Geçirilen bilgiler aşağıdaki ortak etkinlik nesnesi alanlarını içerir:

Chat'te, uygulama ana sayfası etkinlik nesnesi, kullanıcı ve etkileşim zamanı hakkında bilgi içeren chat alanını da içerir:

  • chat.user: Ana Sayfa sekmesini açan Chat kullanıcısı.
  • chat.eventTime: Kullanıcının Ana Sayfa sekmesini açtığı zaman damgası.

Daha fazla bilgi için Etkinlik nesnesi başlıklı makaleyi inceleyin.

Diğer bağlam dışı kartlar

Eklenti kullanıcı arayüzünüzde, ana sayfalar olmayan bağlam dışı ek kartlar bulunabilir. Örneğin, ana sayfanızda eklenti ayarlarını düzenlemek için bir "Ayarlar" kartı açan bir düğme olabilir (bu tür ayarlar genellikle bağlamdan bağımsızdır).

Bağlam dışı kartlar, diğer kartlar gibi oluşturulur. Aralarındaki tek fark, kartı oluşturan ve görüntüleyen işlem veya etkinliktir. Kartlar arasında geçiş oluşturma hakkında ayrıntılı bilgi için Navigasyon yöntemleri başlıklı makaleyi inceleyin.