Mesaj kullanıcı arayüzünü genişletme

Gmail'i genişleten Google Workspace eklentileri, kullanıcı iletileri okurken bir kullanıcı arayüzü sağlayabilir. Bu sayede Google Workspace eklentileri, ileti içeriğine yanıt veren görevleri (ör. iletiyle ilgili ek bilgileri görüntüleme, alma veya gönderme) otomatikleştirebilir.

Eklenti mesajı kullanıcı arayüzüne erişme

Eklentilerin mesaj kullanıcı arayüzünü görüntülemenin iki yolu vardır. İlk yöntem, eklenti açıkken bir iletiyi açmaktır (örneğin, Gmail gelen kutusu penceresinde eklenti ana sayfasını görüntülerken). İkinci yöntem, bir iletiyi görüntülerken eklentiyi başlatmaktır.

Her iki durumda da eklenti, eklenti manifestinde tanımlanan ilgili bağlam tetikleyici işlevini yürütür. Tetikleyici, eklenti açıkken kullanıcı farklı bir iletiye geçerse de çalışır. İçerikle ilgili tetikleyici işlevi, ilgili ileti için ileti kullanıcı arayüzünü oluşturur. Gmail bu kullanıcı arayüzünü kullanıcıya gösterir.

Mesaj eklentisi oluşturma

Aşağıdaki genel adımları uygulayarak bir eklentiye mesaj işlevi ekleyebilirsiniz:

  1. Mesaj işlevi için gereken kapsamlar da dahil olmak üzere, eklenti komut dosyası projesi manifest dosyasına uygun alanları ekleyin. Manifeste, {} değerine sahip bir unconditional koşullu tetikleyici alanı eklediğinizden emin olun.
  2. Kullanıcı bir mesajda eklentiyi seçtiğinde mesaj kullanıcı arayüzü oluşturan bir bağlamsal tetikleyici işlevi uygulayın.
  3. Kullanıcının kullanıcı arayüzü etkileşimlerine yanıt vermek için gereken ilişkili işlevleri uygulayın.

Bağlamsal tetikleyiciler

Google Workspace eklentileri, kullanıcılara iletileri okurken yardımcı olmak için manifest dosyalarında bağlamsal tetikleyici tanımlayabilir. Kullanıcı, tetikleyici ölçütlerini karşılayan bir Gmail iletisini (eklenti açıkken) açtığında* tetikleyici etkinleştirilir. Tetiklenen bir tetikleyici, eklenti kullanıcı arayüzünü oluşturan ve Gmail'in göstermesi için döndüren bir bağlamsal tetikleyici işlevi yürütür. Bu noktada kullanıcı, öğeyle etkileşime geçebilir.

İçeriğe dayalı tetikleyiciler, eklentinizin proje manifestinde tanımlanır. Tetikleyici tanımı, Gmail'e hangi tetikleyici işlevinin hangi koşullar altında tetikleneceğini bildirir. Örneğin, bu manifest snippet'i bir mesaj açıldığında onGmailMessageOpen() tetikleyici işlevini çağıran koşulsuz bir tetikleyici ayarlar:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Bağlamsal tetikleyici işlevi

Her bağlamsal tetikleyicinin, eklentinizin kullanıcı arayüzünü oluşturan karşılık gelen bir tetikleyici işlevi olmalıdır. Bu işlevi manifest'inizin onTriggerFunction alanında belirtirsiniz. Bu işlevi, bir işlem etkinliği nesnesi bağımsız değişkenini kabul etmek ve tek bir Card nesnesi veya Card nesnesi dizisi döndürmek için uygularsınız.

Belirli bir Gmail iletisi için bağlama dayalı bir tetikleyici etkinleştirildiğinde bu işlev çağrılır ve işleve bir işlem etkinliği nesnesi iletilir. Tetikleyici işlevler genellikle Apps Script'in Gmail hizmetini kullanarak ileti metnini ve diğer ayrıntıları almak için bu etkinlik nesnesi tarafından sağlanan ileti kimliğini kullanır. Örneğin, tetikleyici işleviniz şu işlevleri kullanarak mesaj içeriğini ayıklayabilir:

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

Tetikleyici işlevi daha sonra bu veriler üzerinde işlem yapabilir ve arayüz için ihtiyaç duyduğu bilgileri ayıklayabilir. Örneğin, satış rakamlarını özetleyen bir eklenti, ileti gövdesinden satış rakamlarını toplayabilir ve bunları kart şeklinde görüntülemek üzere düzenleyebilir.

Tetikleyici işlevi, bir dizi yerleşik Card nesnesi oluşturmalı ve döndürmelidir. Örneğin, aşağıdaki kod, yalnızca iletinin konusunu ve gönderenini listeleyen tek bir kart içeren bir eklenti oluşturur:

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }