Evrensel işlemler

Evrensel işlemler, kullanıcının seçildiğinde yeni bir web sayfası açmasına, yeni kullanıcı arayüzü kartları görüntülemesine veya belirli bir Apps Komut Dosyası işlevini çalıştırmasına olanak tanıyan menü öğesi öğeleridir. Evrensel işlemler, kart işlemlerine çok benzer. Ancak evrensel işlemler, mevcut eklenti bağlamından bağımsız olarak eklentinizdeki her karta yerleştirilir.

Evrensel işlemleri kullanarak, kullanıcıların eklentinizin hangi bölümüyle etkileşimde bulunduklarına bakılmaksızın belirli işlevlere her zaman erişebilmelerini sağlayabilirsiniz. Evrensel işlemlerle ilgili bazı örnek kullanım alanları:

  • Bir ayarlar web sayfasını açın (veya bir ayarlar kartı görüntüleyin).
  • Kullanıcıya yardım bilgilerini gösterin.
  • "Yeni müşteri ekle" gibi yeni bir iş akışı başlatın.
  • Kullanıcının eklentiyle ilgili geri bildirim göndermesine olanak tanıyan bir kart gösterin.

Mevcut bağlama bağlı olmayan bir işlem yaptığınızda, bu işlemi evrensel bir işlem haline getirmeyi düşünebilirsiniz.

Evrensel işlemleri kullanma

Evrensel işlemler, eklentinizin proje manifestinde yapılandırılır. Evrensel bir işlemi yapılandırdıktan sonra, eklentinizin kullanıcıları bu işlemi her zaman kullanabilir. Kullanıcı bir kartı görüntülüyorsa tanımladığınız evrensel işlemler grubu her zaman kart menüsünde, bu kart için tanımladığınız kart işlemlerinden sonra görünür. Evrensel işlemler, eklentinin manifest dosyasında tanımlandıkları sırayla kart menülerinde görünür.

Evrensel işlemleri yapılandırma

Evrensel işlemleri eklentinizin manifest dosyasında yapılandırırsınız. Daha fazla bilgi için Manifestler başlıklı makaleyi inceleyin.

Her işlem için, menüde görünmesi gereken metni belirtirsiniz. Ardından, işlemin doğrudan yeni bir sekmede web sayfası açması gerektiğini belirten bir openLink alanı belirtebilirsiniz. Alternatif olarak, evrensel işlem seçildiğinde yürütülecek bir Apps Komut Dosyası geri çağırma işlevini belirten bir runFunction alanı belirtebilirsiniz.

runFunction kullanıldığında, belirtilen geri çağırma işlevi genellikle aşağıdakilerden birini yapar:

  • Oluşturulmuş bir UniversalActionResponse nesnesi döndürerek hemen görüntülenecek kullanıcı arayüzü kartları oluşturur.
  • Oluşturulmuş bir UniversalActionResponse nesnesi döndürerek, belki başka görevleri tamamladıktan sonra bir URL açar.
  • Yeni bir karta geçmeyen veya URL açmayan arka plan görevlerini yürütür. Bu durumda geri çağırma işlevi hiçbir şey döndürmez.

Geri çağırma işlevi çağrıldığında, açık kart ve eklenti bağlamı hakkında bilgi içeren bir etkinlik nesnesi iletilir.

Örnek

Aşağıdaki kod snippet'inde, Gmail'i genişletirken evrensel işlemleri kullanan bir Google Workspace eklentisine ait örnek bir manifest alıntısı gösterilmektedir. Kod, eklentinin açık iletiyi kimin gönderdiğini belirleyebilmesi için meta veri kapsamını açıkça ayarlar.

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

Önceki örnekte tanımlanan üç evrensel işlem şunları yapar:

  • google.com'u aç, yeni sekmede https://www.google.com adresini açar.
  • Open contact URL (İletişim URL'sini aç) işlevi, hangi URL'nin açılacağını belirler ve ardından OpenLink nesnesini kullanarak yeni bir sekmede açar. Kod, URL'yi gönderenin e-posta adresini kullanarak oluşturur.
  • Ayarları aç, eklenti komut dosyası projesinde tanımlanan createSettingsCards() işlevini çalıştırır. Bu işlev, eklenti ayarı ve diğer bilgileri içeren bir kart grubu içeren geçerli bir UniversalActionResponse nesnesi döndürür. İşlev bu nesneyi oluşturmayı tamamladıktan sonra kullanıcı arayüzünde kart listesi gösterilir (bkz. Birden fazla kart döndürme).
  • Arka plan senkronizasyonunu çalıştır, eklenti komut dosyası projesinde tanımlanan runBackgroundSync() işlevini çalıştırır. Bu işlev kart oluşturmaz. Bunun yerine, kullanıcı arayüzünü değiştirmeyen başka arka plan görevleri gerçekleştirir. İşlev bir UniversalActionResponse döndürmediğinden, işlev tamamlandığında kullanıcı arayüzünde yeni bir kart gösterilmez. Bunun yerine, işlev çalışırken kullanıcı arayüzünde yükleme göstergesi olarak bir spinner görüntülenir.

openContactURL(), createSettingsResponse() ve runBackgroundSync() işlevlerini nasıl oluşturabileceğinize dair bir örneği aşağıda bulabilirsiniz:

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}