Ações da agenda

Com os objetos Action, é possível criar um comportamento interativo em complementos do Google Workspace. Eles definem o que acontece quando um usuário interage com um widget (por exemplo, um botão) na interface do complemento.

Uma ação é anexada a um determinado widget usando uma função de manipulador de widget, que também define a condição que aciona a ação. Quando acionada, a ação executa uma função de callback designada. A função de callback recebe um objeto de evento que contém informações sobre as interações do usuário no lado do cliente. Você precisa implementar a função de callback e fazer com que ela retorne um objeto de resposta específico.

Por exemplo, digamos que você queira um botão que crie e mostre um novo card quando clicado. Para isso, crie um novo widget de botão e use a função setOnClickAction(action) do gerenciador de widget de botão para definir um Action de criação de ficha de informações. O Action que você define especifica uma função de callback do Apps Script que é executada quando o botão é clicado. Nesse caso, você implementa a função de callback para criar o card desejado e retorna um objeto ActionResponse. O objeto de resposta informa ao complemento para mostrar o card criado pela função de callback.

Esta página descreve as ações de widgets específicas do Google Agenda que podem ser incluídas no complemento.

Interações com o Google Agenda

Os complementos do Google Workspace que estendem o Agenda podem incluir outras ações de widget específicas do Agenda. Essas ações exigem que a função de callback associada retorne objetos de resposta especializados:

Ação tentada A função de callback precisa retornar
Adicionar participantes CalendarEventActionResponse
Definir dados de conferência CalendarEventActionResponse
Como adicionar anexos CalendarEventActionResponse

Para usar essas ações de widget e objetos de resposta, todas as condições a seguir precisam ser verdadeiras:

  • A ação é acionada enquanto o usuário tem um evento da Agenda aberto.
  • O campo de manifesto addOns.calendar.currentEventAccess do complemento do Google Workspace está definido como WRITE ou READ_WRITE.
  • O complemento inclui o https://www.googleapis.com/auth/calendar.addons.current.event.write escopo do Google Agenda.

As mudanças feitas pela função de callback da ação não são salvas até que o usuário salve o evento do Google Agenda.

Adicionar participantes com uma função de callback

O exemplo a seguir mostra como criar um botão que adiciona um convidado específico a um evento da agenda em edição. Este exemplo usa uma estrutura básica de card:

/**
 * Build a basic card with a button that sends a notification.
 * This function is called as part of the eventOpenTrigger that builds
 * a UI when the user opens an event.
 *
 * @param e The event object passed to eventOpenTrigger function.
 * @return {Card}
 */
function buildSimpleCard(e) {
  var buttonAction = CardService.newAction()
      .setFunctionName('onAddAttendeesButtonClicked');
  var button = CardService.newTextButton()
      .setText('Add new attendee')
      .setOnClickAction(buttonAction);

  // Check the event object to determine if the user can add
  // attendees and disable the button if not.
  if (!e.calendar.capabilities.canAddAttendees) {
    button.setDisabled(true);
  }

  // ...continue creating card sections and widgets, then create a Card
  // object to add them to. Return the built Card object.
}

/**
 * Callback function for a button action. Adds attendees to the
 * Calendar event being edited.
 *
 * @param {Object} e The action event object.
 * @return {CalendarEventActionResponse}
 */
function onAddAttendeesButtonClicked (e) {
  return CardService.newCalendarEventActionResponseBuilder()
      .addAttendees(["aiko@example.com", "malcom@example.com"])
      .build();
}

Definir dados de conferência com uma função de callback

Essa ação define os dados da conferência no evento aberto. Para esses dados de conferência, o ID da solução precisa ser especificado porque a ação não foi acionada pelo usuário ao selecionar a solução desejada.

O exemplo a seguir mostra como criar um botão que define dados de conferência para um evento em edição:

/**
 * Build a basic card with a button that sends a notification.
 * This function is called as part of the eventOpenTrigger that builds
 * a UI when the user opens a Calendar event.
 *
 * @param e The event object passed to eventOpenTrigger function.
 * @return {Card}
 */
function buildSimpleCard(e) {
  var buttonAction = CardService.newAction()
      .setFunctionName('onSaveConferenceOptionsButtonClicked')
      .setParameters(
        {'phone': "1555123467", 'adminEmail': "joyce@example.com"});
  var button = CardService.newTextButton()
      .setText('Add new attendee')
      .setOnClickAction(buttonAction);

  // Check the event object to determine if the user can set
  // conference data and disable the button if not.
  if (!e.calendar.capabilities.canSetConferenceData) {
    button.setDisabled(true);
  }

  // ...continue creating card sections and widgets, then create a Card
  // object to add them to. Return the built Card object.
}

/**
 * Callback function for a button action. Sets conference data for the
 * Calendar event being edited.
 *
 * @param {Object} e The action event object.
 * @return {CalendarEventActionResponse}
 */
function onSaveConferenceOptionsButtonClicked(e) {
  var parameters = e.commonEventObject.parameters;

  // Create an entry point and a conference parameter.
  var phoneEntryPoint = ConferenceDataService.newEntryPoint()
    .setEntryPointType(ConferenceDataService.EntryPointType.PHONE)
    .setUri('tel:' + parameters['phone']);

  var adminEmailParameter = ConferenceDataService.newConferenceParameter()
      .setKey('adminEmail')
      .setValue(parameters['adminEmail']);

  // Create a conference data object to set to this Calendar event.
  var conferenceData = ConferenceDataService.newConferenceDataBuilder()
      .addEntryPoint(phoneEntryPoint)
      .addConferenceParameter(adminEmailParameter)
      .setConferenceSolutionId('myWebScheduledMeeting')
      .build();

  return CardService.newCalendarEventActionResponseBuilder()
      .setConferenceData(conferenceData)
      .build();
}

Adicionar anexos com uma função de callback

O exemplo a seguir mostra como criar um botão que adiciona um anexo a um evento da Agenda em edição:

/**
 * Build a basic card with a button that creates a new attachment.
 * This function is called as part of the eventAttachmentTrigger that
 * builds a UI when the user goes through the add-attachments flow.
 *
 * @param e The event object passed to eventAttachmentTrigger function.
 * @return {Card}
 */
function buildSimpleCard(e) {
  var buttonAction = CardService.newAction()
      .setFunctionName('onAddAttachmentButtonClicked');
  var button = CardService.newTextButton()
      .setText('Add a custom attachment')
      .setOnClickAction(buttonAction);

  // Check the event object to determine if the user can add
  // attachments and disable the button if not.
  if (!e.calendar.capabilities.canAddAttachments) {
    button.setDisabled(true);
  }

  // ...continue creating card sections and widgets, then create a Card
  // object to add them to. Return the built Card object.
}

/**
 * Callback function for a button action. Adds attachments to the
 * Calendar event being edited.
 *
 * @param {Object} e The action event object.
 * @return {CalendarEventActionResponse}
 */
function onAddAttachmentButtonClicked(e) {
  return CardService.newCalendarEventActionResponseBuilder()
           .addAttachments([
             CardService.newAttachment()
               .setResourceUrl("https://example.com/test")
               .setTitle("Custom attachment")
               .setMimeType("text/html")
               .setIconUrl("https://example.com/test.png")
           ])
      .build();
}

Definir o ícone de anexo

O ícone de anexo precisa ser hospedado na infraestrutura do Google. Consulte Fornecer ícones de anexos para mais detalhes.