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. Çalışmalarında kart işlemlerine çok benzerler. Ancak evrensel işlemler, mevcut eklenti bağlamı ne olursa olsun her zaman eklentinizdeki tüm kartlara yerleştirilir.

Evrensel işlemler kullanarak, eklentinizin hangi kısmıyla etkileşimde bulunursa bulunsun kullanıcının her zaman belirli işlevlere erişebilmesini sağlayabilirsiniz. Aşağıda, evrensel eylemlere ilişkin bazı örnek kullanım alanları verilmiştir:

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

Mevcut bağlama bağlı olmayan bir işleminiz olduğunda bunu evrensel bir işlem haline getirmeyi düşünmelisiniz.

Evrensel işlemleri kullanma

Evrensel işlemler, eklentinizin proje manifest'inde yapılandırılır. Evrensel işlem yapılandırdıktan sonra, eklentinizin kullanıcıları her zaman bu işlemi 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 tüm kart işlemlerinden sonra görünür. Evrensel işlemler, kart menülerinde, eklentinin manifest dosyasında tanımlandıkları sırayla 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 ayrıntı için Manifest'ler bölümüne bakın.

Her işlem için, o işleme ait menüde görünmesi gereken metni belirtirsiniz. Ardından, işlemin bir web sayfasını doğrudan yeni bir sekmede 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 runFunction alanı belirtebilirsiniz.

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

  • Yerleşik bir UniversalActionResponse nesnesi döndürerek hemen görüntülenecek kullanıcı arayüzü kartları oluşturur.
  • Başka görevler yaptıktan sonra, derlenmiş bir UniversalActionResponse nesnesini döndürerek URL açar.
  • Yeni karta geçiş yapmayan veya bir URL'yi açmayan arka plan görevleri gerçekleştirir. Bu durumda, geri çağırma işlevi hiçbir şey döndürmez.

Çağrı yapıldığında, geri çağırma işlevine 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şlemler kullanan bir Google Workspace eklentisine ilişkin örnek bir manifest alıntısı gösterilmektedir. Kod açıkça bir meta veri kapsamı ayarlar. Böylece eklenti, açık mesajı kimin gönderdiğini belirleyebilir.

  "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ç seçeneği, https://www.google.com'u yeni bir sekmede açar.
  • Kişi URL'sini aç seçeneği, hangi URL'nin açılacağını belirleyen bir işlev çalıştırır ve ardından bunu bir OpenLink nesnesi kullanarak yeni sekmede açar. Kod, gönderenin e-posta adresini kullanarak URL'yi oluşturur.
  • Ayarları aç, eklenti komut dosyası projesinde tanımlanan createSettingsCards() işlevini çalıştırır. Bu işlev, eklenti ayarı ve başka bilgiler içeren bir dizi kart içeren geçerli bir UniversalActionResponse nesnesi döndürür. İşlev bu nesneyi oluşturmayı bitirdikten sonra, kullanıcı arayüzünde kart listesi görüntülenir (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 derlemez. Bunun yerine, kullanıcı arayüzünü değiştirmeyen bazı arka plan görevlerini yerine getirir. İş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 bir yükleme göstergesi döner simgesi görüntüler.

Aşağıda openContactURL(), createSettingsResponse() ve runBackgroundSync() işlevlerini nasıl oluşturabileceğinize dair bir örnek verilmiştir:

/**
 * 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.
}