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

Gmail'in kapsamını genişleten Google Workspace Eklentileri, kullanıcılar iletileri okurken bir kullanıcı arayüzü sağlayabilir. Bu durum, Google Workspace Eklentilerinin mesaj içeriğine yanıt veren görevleri (mesajla ilgili ek bilgileri görüntüleme, alma veya gönderme gibi) otomatikleştirmesine olanak tanır.

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

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

Her iki durum da eklentinin, eklenti manifest dosyasında tanımlanan ilgili içerik tetikleyici işlevini yürütmesine neden olur. Tetikleyici, kullanıcı eklenti açıkken farklı bir mesaja geçerse de yürütülür. Bağlamsal tetikleyici işlevi, söz konusu mesaj için mesaj kullanıcı arayüzünü oluşturur ve 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. Manifest dosyasına {} unconditional değerine sahip bir koşullu tetikleyici alanı eklediğinizden emin olun.
  2. Kullanıcı bir mesajda eklentiyi seçtiğinde bir mesaj kullanıcı arayüzü oluşturan içeriğe dayalı bir 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, mesajları okurken kullanıcılara yardımcı olmak için manifest dosyalarında bağlamsal bir tetikleyici tanımlayabilir. Kullanıcı, tetikleyici ölçütlerini* karşılayan bir Gmail iletisini (eklenti açıkken) açtığında tetikleyici etkinleşir. Tetiklenen tetikleyici, eklenti kullanıcı arayüzünü oluşturan ve Gmail'in görüntülemesi için döndüren bir içerik tetikleyici işlevi yürütür. Bu noktada kullanıcı etkileşimde bulunmaya başlayabilir.

İçeriğe dayalı tetikleyiciler, eklentinizin proje manifestinde tanımlanır. Tetikleyici tanımı, Gmail'e hangi işlevin hangi koşullar altında etkinleşeceğ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 içeriğe dayalı tetikleyicinin, eklentinizin kullanıcı arayüzünü oluşturan karşılık gelen bir tetikleyici işlevi olmalıdır. Bu işlevi manifest dosyanızın 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 nesnesini veya bir Card nesne dizisi döndürmek için uygularsınız.

Belirli bir Gmail iletisi için bağlamsal tetikleyici etkinleştiğinde, tetikleyici bu işlevi çağırır ve onu bir eylem etkinliği nesnesi iletir. Tetikleyici işlevleri, Apps Komut Dosyası'nın Gmail hizmetini kullanarak mesaj metnini ve diğer ayrıntıları almak için genellikle bu etkinlik nesnesi tarafından sağlanan mesaj kimliğini kullanır. Örneğin, tetikleyici işleviniz şu işlevleri kullanarak ileti içeriğini çıkarabilir:

  // 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();

Daha sonra tetikleyici işlevi, arayüz için ihtiyaç duyduğu bilgileri ayıklayarak bu veriler üzerinde işlem yapabilir. Örneğin, satış numaralarını özetleyen bir eklenti, satış rakamlarını mesaj gövdesinden toplayabilir ve bunları bir kart içinde görüntülenecek şekilde düzenleyebilir.

Tetikleyici işlevi, bir dizi derleme Card nesnesi derleyip döndürmelidir. Örneğin, aşağıda yalnızca mesajın konusu ve gönderenini listeleyen tek bir karta sahip bir eklenti oluşturulur:

  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];
  }