Evrensel işlemler

Evrensel işlemler, kullanıcının yeni bir öğe açmasına olanak tanıyan menü öğesi öğeleridir yeni kullanıcı arayüzü kartları görüntüleyebilir veya belirli bir Apps Komut Dosyası'nı seçili. İşleyiş şekli açısından kart işlemleri Ancak evrensel işlemlerin her zaman eklentinizdeki her karta yerleştirilmesi, bağlamdan bağımsız olarak dikkate alınır.

Evrensel işlemler kullanarak kullanıcının her zaman eklentinizin hangi bölümüyle etkileşime girdiğine bakılmaksızın belirli somut olarak ortaya koyar. 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 eylem haline getirmeyi düşünmelisiniz.

Evrensel işlemleri kullanma

Evrensel işlemler, eklentinizin projesinde yapılandırıldı manifest dosyası için de kullanılabilir. Bu sorunu çözmek için her zaman eklentinizin kullanıcıları tarafından kullanılabilir. Kullanıcı bir kartı görüntülerken, tanımladığınız evrensel işlemler kümesi her zaman kart menüsünde kart işlemleri özelliklerini de kullanabilirsiniz. Evrensel işlemler, manifest dosyasında tanımlandıkları sırayla aynı olmalıdır.

Evrensel işlemleri yapılandırma

Evrensel işlemleri eklentinizin manifest dosyasında yapılandırırsınız; bkz. Manifestler inceleyebilirsiniz.

Her işlem için menüde görünmesi gereken metni eyleme dökülebilir. Ardından, işlemin yapıldığını belirten bir openLink alanı belirtebilirsiniz. doğrudan yeni bir sekmede web sayfası açmalıdır. Alternatif olarak, Apps Komut Dosyası geri çağırma işlevini belirten bir runFunction alanı evrensel işlem seçildiğinde yürütülür.

runFunction kullanıldığında, belirtilen geri çağırma işlevi genellikle bir şunlardan biri:

  • Yerleşik bir kodu döndürerek hemen görüntülenecek kullanıcı arayüzü kartları UniversalActionResponse nesnesini tanımlayın.
  • Örneğin, diğer görevleri yaptıktan sonra, yerleşik bir UniversalActionResponse nesne algılandı.
  • 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şlevi etkinlik nesnesi Açık kart ve eklenti bağlamı hakkında bilgi içeren

Örnek

Aşağıdaki kod snippet'i, Evrensel işlemleri kullanan Google Workspace eklentisi ve Gmail'in kapsamını genişletir. Kod açık bir şekilde meta veri kapsamını ayarlar. Böylece, 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 şunları yapar:

  • Google.com'u aç seçeneği, https://www.google.com'u tıklayın.
  • İletişim URL'sini aç, hangi URL'nin açılacağını belirleyen bir işlev çalıştırır ve sonra şunu kullanarak yeni bir sekmede açar: OpenLink nesnesini tıklayın. İlgili içeriği oluşturmak için kullanılan kodu, gönderenin e-posta adresini kullanarak URL'yi oluşturur.
  • Ayarları aç, şurada tanımlanan createSettingsCards() işlevini çalıştırır: komut dosyası projesidir. Bu işlev, UniversalActionResponse eklenti ayarı ve başka bilgiler içeren bir dizi kart içeren nesne İşlev bu nesneyi oluşturmayı bitirdikten sonra kullanıcı arayüzünde liste görüntülenir (bkz. Birden fazla kartı iade etme).
  • Arka plan senkronizasyonunu çalıştır,runBackgroundSync() komut dosyası projesidir. Bu işlev kart derlemez; onun yerine kullanıcı arayüzünü değiştirmeyen diğer bazı arka plan görevlerini yerine getirir. işlevi, UniversalActionResponse işlev tamamlandığında kullanıcı arayüzünde yeni bir kart görüntülenmiyor. Bunun yerine Kullanıcı arayüzünde, işlev çalışırken bir yükleme göstergesi döner simgesi gösteriliyor.

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

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