Evrensel işlemler

Evrensel işlemler, kullanıcının yeni bir web sayfası açmasına, yeni kullanıcı arayüzü kartları göstermesine veya seçildiğinde belirli bir Apps Script işlevini çalıştırmasına olanak tanıyan menü öğesi öğeleridir. İşlevsel olarak kart işlemlerine çok benzerler. Tek fark, evrensel işlemlerin mevcut eklenti bağlamından bağımsız olarak eklentinizdeki her karta her zaman yerleştirilmesidir.

Evrensel işlemleri kullanarak, kullanıcının eklentinizin hangi kısmıyla etkileşime geçtiğinden bağımsız olarak belirli işlevlere her zaman erişebildiğinden emin olabilirsiniz. Evrensel işlemler için bazı örnek kullanım alanları şunlardır:

  • Bir ayarlar web sayfasını açın (veya bir ayarlar kartı gösterin).
  • Kullanıcıya yardım bilgilerini gösterin.
  • "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üşünmeniz gerekir.

Evrensel işlemleri kullanma

Evrensel işlemler, eklentinizin proje manifestinde yapılandırılır. Yapılandırdığınız evrensel işlemler, eklentinizin kullanıcıları tarafından her zaman kullanılabilir. Kullanıcı bir kartı görüntülüyorsa tanımladığınız evrensel işlemler grubu, kart menüsünde her zaman ilgili kart için tanımladığınız 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

Universal işlemleri, eklentinizin manifest dosyasında yapılandırırsınız. Daha fazla bilgi için Manifestler bölümüne bakın.

Her işlem için, ilgili işlemin menüsünde görünmesi gereken metni belirtirsiniz. Ardından, işlemin doğrudan bir web sayfasını yeni bir sekmede açması gerektiğini belirten bir openLink alanı belirtebilirsiniz. Alternatif olarak, evrensel işlem seçildiğinde çalıştırılacak bir Apps Script geri çağırma işlevini belirten bir runFunction alanı da belirtebilirsiniz.

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

  • Hazır bir UniversalActionResponse nesnesi döndürerek hemen gösterilecek kullanıcı arayüzü kartları oluşturur.
  • Oluşturulan bir UniversalActionResponse nesnesini döndürerek, belki de diğer görevleri yaptı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 eklentisi için ö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 belirler.

  "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 aşağıdakileri yapar:

  • google.com'u aç, https://www.google.com adresini yeni bir sekmede açar.
  • İletişim URL'sini aç, hangi URL'nin açılacağını belirleyen bir işlev çalıştırır ve ardından OpenLink nesnesi kullanarak bu URL'yi 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ını 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ü kart listesini gösterir (Birden fazla kart döndürme bölümüne bakın).
  • 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 sona erdiğinde kullanıcı arayüzünde yeni bir kart gösterilmez. Bunun yerine, işlev çalışırken kullanıcı arayüzünde bir yükleme göstergesi döner.

openContactURL(), createSettingsResponse() ve runBackgroundSync() işlevlerini nasıl oluşturabileceğinize dair bir örnek aşağıda 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.
}