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

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

Google Workspace 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şlevi yürütür. Eklenti açıkken kullanıcı farklı bir iletiye geçerse tetikleyici yine ç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şlevselliği 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ğlama duyarlı 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

Eklentiler, 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ı, cihazla etkileşime geçmeye başlayabilir.

Bağlamsal tetikleyiciler, eklentinizin proje manifestinde tanımlanır. Tetikleyici tanımı, hangi koşullarda hangi tetikleyici işlevinin tetikleneceğini Gmail'e bildirir. Örneğin, bu manifest snippet'i, bir ileti açıldığında tetikleyici işlevini onGmailMessageOpen() ç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 dosyanızın onTriggerFunction alanında belirtirsiniz. Bu işlevi, bir action event object bağımsız değişkenini kabul edecek ve tek bir Card nesnesi ya da bir Card nesneleri dizisi döndürecek şekilde 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. Çoğu durumda, diğer Gmail hizmeti işlevlerini kullanmadan önce etkinlik nesnesi tarafından sağlanan erişim jetonunu ve GmailApp.setCurrentMessageAccessToken(accessToken) işlevini kullanarak Gmail kapsamlarını etkinleştirmeniz gerekir. Örneğin, tetikleyici işleviniz aşağıdaki 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şlev daha sonra bu veriler üzerinde işlem yaparak arayüz için ihtiyaç duyduğu bilgileri ayıklayabilir. Örneğin, satış rakamlarını özetleyen bir eklenti, satış rakamlarını e-posta mesajından toplayıp kartta gösterecek şekilde düzenleyebilir.

Tetikleyici işlevi, oluşturulmuş Card nesneler dizisi oluşturup döndürmelidir. Örneğin, aşağıdakiler 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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}