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

Gmail'i genişleten Google Workspace eklentileri, kullanıcı ileti okurken 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ştirir.

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

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

Her iki durumda da eklenti, eklenti manifest dosyasında tanımlanan ilgili bağlamsal tetikleyici işlevini yürütür. Eklenti açıkken kullanıcı farklı bir iletiye geçerse de tetikleyici çalışır. Bağlama dayalı tetikleyici işlevi, bu ileti için ileti kullanıcı arayüzünü oluşturur. Gmail, bu arayüzü kullanıcıya gösterir.

Mesaj eklentisi oluşturma

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

  1. Eklenti komut dosyası projesinin manifest dosyasına uygun alanları ekleyin. Bu alanlar, mesaj işlevi için gerekli olan kapsamları da içerir. Manifeste, {} değerine sahip bir unconditional koşullu tetikleyici alanı eklediğinizden emin olun.
  2. Kullanıcı bir iletide eklentiyi seçtiğinde ileti kullanıcı arayüzü oluşturan bağlamsal 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, kullanıcılara mesaj okurken yardımcı olmak için manifestlerinde bağlamsal tetikleyici tanımlayabilir. Kullanıcı, tetikleyici ölçütlerini karşılayan bir Gmail iletisini (eklenti açıkken) açtığında tetikleyici çalışır*. Tetiklenen bir tetikleyici, eklenti kullanıcı arayüzünü oluşturan ve Gmail'in görüntülemesi için döndüren bir bağlamsal tetikleyici işlevi yürütür. Bu noktada kullanıcı, uygulamayla etkileşime geçebilir.

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

{
  ...
  "addOns": {

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

Bağlamsal tetikleme 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 dosyanızın onTriggerFunction alanında belirtirsiniz. Bu işlevi, bir action event object bağımsız değişkenini kabul etmek ve tek bir Card nesnesi ya da bir Card nesneleri dizisi döndürmek için uygularsınız.

Belirli bir Gmail iletisi için bağlamsal tetikleyici tetiklendiğinde bu işlev çağrılır ve işlem etkinliği nesnesi iletilir. Genellikle tetikleyici işlevler, Apps Komut Dosyası'nın 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, aşağıdaki işlevleri kullanarak ileti 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şlev daha sonra bu veriler üzerinde işlem yaparak arayüz için ihtiyaç duyduğu bilgileri ayıklayabilir. Örneğin, satış raketlerini özetleyen bir eklenti, ileti gövdesindeki satış rakamlarını toplayıp kartta görüntülenmek üzere düzenleyebilir.

Tetikleyici işlevi, oluşturulan Card nesnelerden oluşan bir dizi oluşturup döndürmelidir. Örneğin, aşağıda yalnızca iletinin konusunu ve gönderenini listeleyen tek bir kart içeren 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];
  }