Google Workspace Add-on bouwen

Workspace Add-on of Editor Add-on

Er zijn twee soorten add-ons in het Google-ecosysteem, en het is belangrijk dat je vooraf het juiste type kiest:

• Editor Add-ons: draaien in Sheets, Docs, Slides en Forms via het menu Extensies. Ze zijn alleen beschikbaar als de gebruiker het betreffende bestand open heeft, en kunnen een eigen zijbalk tonen met HtmlService.
• Workspace Add-ons: verschijnen in de zijbalk van Gmail, Drive, Calendar, Docs, Sheets, Slides en Meet. Ze gebruiken het Cards-framework en werken over meerdere apps tegelijk.

Dit artikel behandelt Workspace Add-ons op basis van het moderne Cards-framework. Dat is de aanbevolen aanpak als je dezelfde add-on in meerdere Google-apps wilt aanbieden.

Manifest configureren

Het appsscript.json manifest definieert de triggers, het runtime en de OAuth-scopes. Schakel in de Apps Script-editor eerst Project Settings en de optie Show appsscript.json manifest file in editor in.

{
  "timeZone": "Europe/Amsterdam",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Mijn Add-on",
      "logoUrl": "https://example.com/icon.png",
      "homepageTrigger": {
        "runFunction": "buildHomepageCard"
      }
    },
    "gmail": {
      "contextualTriggers": [{
        "unconditional": {},
        "onTriggerFunction": "buildGmailContextCard"
      }]
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/script.locale"
  ]
}

De homepageTrigger onder common bouwt de niet-contextuele beginpagina van je add-on, die in elke ondersteunde host verschijnt. De contextualTriggers onder gmail reageren op een geopend bericht. Een contextuele Gmail-trigger ondersteunt op dit moment alleen het criterium unconditional, wat betekent dat hij voor elk geopend bericht afgaat.

Homepage card bouwen

De homepage-functie geeft een Card-object terug dat in de zijbalk verschijnt:

function buildHomepageCard() {
  const card = CardService.newCardBuilder();
  card.setName('homepage');

  const header = CardService.newCardHeader()
    .setTitle('Mijn Workspace Add-on')
    .setSubtitle('Versie 1.0')
    .setImageUrl('https://example.com/icon.png');
  card.setHeader(header);

  const sectie = CardService.newCardSection()
    .setHeader('Snelle acties');

  const knop1 = CardService.newTextButton()
    .setText('Rapport genereren')
    .setOnClickAction(
      CardService.newAction().setFunctionName('genereerRapport')
    );

  sectie.addWidget(knop1);
  card.addSection(sectie);

  return card.build();
}

Contextuele Gmail-card

Wanneer een gebruiker een e-mail opent, vuurt de contextuele trigger. Het event-object bevat het bericht-ID:

function buildGmailContextCard(e) {
  const berichtId = e.gmail.messageId;
  const bericht = GmailApp.getMessageById(berichtId);

  const card = CardService.newCardBuilder();

  const sectie = CardService.newCardSection()
    .setHeader('E-mailinformatie');

  sectie.addWidget(
    CardService.newKeyValue()
      .setTopLabel('Afzender')
      .setContent(bericht.getFrom())
  );

  sectie.addWidget(
    CardService.newKeyValue()
      .setTopLabel('Datum')
      .setContent(bericht.getDate().toLocaleDateString('nl-NL'))
  );

  const opslaanKnop = CardService.newTextButton()
    .setText('Opslaan in Sheets')
    .setOnClickAction(
      CardService.newAction()
        .setFunctionName('slaEmailDetailsOp')
        .setParameters({berichtId})
    );

  sectie.addWidget(CardService.newButtonSet().addButton(opslaanKnop));
  card.addSection(sectie);

  return card.build();
}

Action-functies implementeren

Een action-functie wordt aangeroepen wanneer de gebruiker op een knop klikt. Ze geeft een ActionResponse terug, bijvoorbeeld om een notificatie te tonen:

function slaEmailDetailsOp(e) {
  const berichtId = e.parameters.berichtId;
  const bericht = GmailApp.getMessageById(berichtId);

  const blad = SpreadsheetApp.openById(
    PropertiesService.getScriptProperties().getProperty('SHEET_ID')
  ).getActiveSheet();

  blad.appendRow([
    new Date(),
    bericht.getFrom(),
    bericht.getSubject(),
    bericht.getDate(),
  ]);

  return CardService.newActionResponseBuilder()
    .setNotification(
      CardService.newNotification().setText('E-mail opgeslagen in Sheets')
    )
    .build();
}

Formulier-invoer in add-ons

Cards ondersteunen invoervelden en keuzelijsten. De ingevulde waarden komen binnen via e.formInput:

function buildFormCard() {
  const sectie = CardService.newCardSection();

  const naamInvoer = CardService.newTextInput()
    .setFieldName('naam')
    .setTitle('Naam')
    .setHint('Volledige naam');

  const categorieDropdown = CardService.newSelectionInput()
    .setType(CardService.SelectionInputType.DROPDOWN)
    .setFieldName('categorie')
    .setTitle('Categorie')
    .addItem('Verkoop', 'verkoop', false)
    .addItem('Support', 'support', true)
    .addItem('Administratie', 'admin', false);

  const verstuurKnop = CardService.newTextButton()
    .setText('Versturen')
    .setOnClickAction(
      CardService.newAction().setFunctionName('verwerkFormulier')
    );

  sectie.addWidget(naamInvoer)
    .addWidget(categorieDropdown)
    .addWidget(CardService.newButtonSet().addButton(verstuurKnop));

  return CardService.newCardBuilder()
    .addSection(sectie)
    .build();
}

function verwerkFormulier(e) {
  const naam = e.formInput.naam;
  const categorie = e.formInput.categorie;

  Logger.log(`Formulier: ${naam}, ${categorie}`);

  return CardService.newActionResponseBuilder()
    .setNotification(CardService.newNotification().setText(`Bedankt, ${naam}!`))
    .build();
}

Testen en deployen

Tijdens de ontwikkeling test je je add-on met een test-deployment, zodat je niet bij elke wijziging opnieuw hoeft te publiceren.

Voor publieke verspreiding heb je een Google Cloud-project nodig met een geconfigureerd OAuth-consentscherm, een ingevulde Google Workspace Marketplace SDK en een review door Google. Houd er rekening mee dat de review enkele dagen tot weken kan duren, vooral bij gevoelige of restricted scopes.

Workspace Add-ons integreren je eigen functionaliteit naadloos in de dagelijkse Google-tools van je team. Met het Cards-framework bouw je consistente UI die in Gmail, Drive, Docs, Sheets en Calendar werkt, terwijl je met scopes, script properties en test-deployments grip houdt op veiligheid en uitrol.