Evrensel işlemler

Evrensel işlemler, seçildiğinde kullanıcının 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ışması açısından kart işlemlerine çok benzerdirler. 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 bölümüyle etkileşim kurduğundan bağımsız olarak her zaman belirli işlevlere erişebildiğinden emin olabilirsiniz. Aşağıda, evrensel işlemlere ilişkin bazı örnek kullanım alanları verilmiştir:

  • Ayarlar web sayfasını açın (veya 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 eklenti hakkında geri bildirim göndermesine olanak tanıyan bir kart görüntüleyin.

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

Evrensel işlemleri kullanma

Evrensel işlemler, eklentinizin proje manifestinde yapılandırılır. Evrensel bir işlem yapılandırdıktan sonra, bu işlem her zaman eklentinizin kullanıcıları tarafından kullanılabilir. Kullanıcı bir kartı görüntülüyorsa, tanımladığınız evrensel işlemler kümesi her zaman kart menüsünde, o kart için tanımladığınız tüm kart işlemlerinden sonra görüntülenir. 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 ayrıntılı bilgi için Manifests sayfasını inceleyin.

Her eylemin menüsünde görünmesi gereken metni belirtirsiniz. Ardından, işlemin doğrudan bir web sayfasını yeni 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şlevinin belirtildiği runFunction alanı belirtebilirsiniz.

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

  • Derlenmiş bir UniversalActionResponse nesnesini döndürerek hemen görüntülenecek kullanıcı arayüzü kartları oluşturur.
  • Belki diğer görevleri yaptıktan sonra, oluşturulmuş bir UniversalActionResponse nesnesini döndürerek bir URL açar.
  • Yeni bir karta geçiş yapılmayan veya bir URL açılmayan arka plan görevleri 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 içeriği 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 Eklentisi için örnek manifest alıntısı gösterilmektedir. Kod, açık bir şekilde meta veri kapsamını ayarlar. Böylece eklenti, açık iletiyi 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 aşağıdakileri yapar:

  • Google.com'u aç seçeneği, yeni bir sekmede https://www.google.com'u açar.
  • Open contact URL (Kişi URL'sini aç) işlevi, hangi URL'nin açılacağını belirleyen bir işlev çalıştırır ve ardından bir OpenLink nesnesi kullanarak bunu yeni bir sekmede açar. Bu 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 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 kartlar listesi görüntülenir (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 bazı diğer arka plan görevlerini gerçekleştirir. İşlev bir UniversalActionResponse döndürmediğinden, işlev tamamlandığında kullanıcı arayüzü yeni bir kart göstermez. Bunun yerine, işlev çalışırken kullanıcı arayüzünde bir yükleme göstergesi döner simgesi görüntülenir.

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