mailinapp
Documentation menu

Blocco Aggiungi al calendario

Un blocco "aggiungi questo al mio calendario" a un tap, e la soluzione pratica per gli inviti tra fusi orari diversi. Un'email inviata non ha JavaScript per rilevare il fuso orario del destinatario, quindi questo blocco codifica l'inizio e la fine dell'evento come un istante assoluto invece che come una stringa in orario locale pre-calcolata. In questo modo, l'app di calendario di ogni partecipante lo mostra correttamente e automaticamente nel proprio orario locale.

Come funziona

Il blocco è contenuto puro, come Sede: non c'è nulla a cui rispondere, quindi non compare mai nella dashboard delle risposte o nell'esportazione CSV. Tutti e tre i link che renderizza si avvalgono dello stesso slot generico di tracciamento dei clic usato da ogni blocco che porta un link semplice, invece di una capability su misura.

I link sono subordinati alla presenza di un startsAt valido: un evento senza orario di inizio impostato renderizza solo il titolo e il testo della descrizione, senza link morti che non portano da nessuna parte. Se startsAt è impostato ma endsAt non lo è (o risolve a un valore precedente a startsAt), il blocco imposta di default la durata a un'ora dopo l'inizio — compilare solo "quando inizia" è trattato come il caso comune, e ogni consumatore a valle (il file .ics, Google Calendar, Outlook.com) ha bisogno che esista un qualche istante di fine. location è un campo digitato liberamente a mano, che compili tu stesso a partire dal testo del tuo blocco Sede o Link della riunione; i tre blocchi non sono collegati automaticamente in questa prima versione, quindi aggiornalo tu stesso se la sede cambia.

A partire da quelle proprietà vengono renderizzati tre link, che condividono un unico blockId ai fini del tracciamento dei clic (la mappa di calore raggruppa per blocco, non per singolo link, la stessa convenzione usata dai link Social per le loro molteplici icone):

  • Scarica .ics — un link firmato verso GET /api/calendar che trasmette in streaming un file RFC 5545 (iCalendar) scritto da zero. Non c'è alcuna dipendenza npm dietro — un file .ics è testo semplice, costruito nello stesso modo "puramente da zero" dell'encoder GIF del conto alla rovescia. DTSTART/DTEND del file vengono emessi come istanti UTC assoluti (una Z finale, senza bisogno di alcun componente TZID/VTIMEZONE) — questa è la vera correzione tra fusi orari, non qualcosa calcolato al momento del rendering, ma solo una conseguenza del fatto che startsAt/endsAt del blocco sono già memorizzati come millisecondi epoch fin dall'inizio. UID dell'evento è un hash sha256 deterministico di titolo/descrizione/posizione/inizio/fine, così riscaricare lo stesso link firmato aggiorna una voce di calendario esistente invece di crearne una duplicata. Il testo digitato liberamente viene sottoposto a escape secondo l'RFC 5545 §3.3.11 (backslash, virgole, punti e virgola, interruzioni di riga letterali) e le righe lunghe vengono spezzate al limite di 75 ottetti richiesto dalla specifica, così una descrizione lunga di un organizzatore non può produrre un file tecnicamente non valido. L'URL stesso è firmato allo stesso modo degli endpoint di conto alla rovescia/formula/grafico — l'intero payload dell'evento viene serializzato nella query string (nessuna lettura da Firestore sul percorso GET), separato per dominio da ogni altra famiglia di URL firmati dell'app tramite un prefisso "calendar:" incorporato nell'input HMAC, così una firma generata per questo endpoint non può mai essere verificata contro un altro.
  • Aggiungi a Google Calendar — un semplice deep link calendar.google.com/calendar/render?action=TEMPLATE&... costruito al momento dell'emissione, senza alcuna chiamata al server.
  • Aggiungi a Outlook.com — un semplice deep link outlook.live.com/calendar/0/action/compose?..., anch'esso costruito al momento dell'emissione.

Titolo, descrizione e posizione vengono ciascuno tagliati per prudenza a lunghezze massime fisse (200 / 2.000 / 300 caratteri) prima che uno qualsiasi dei tre link venga costruito, così un campo digitato liberamente molto lungo non può produrre un link .ics non funzionante o una query string sovradimensionata sui due link web.

Campi configurabili:

  • Titolo dell'evento.
  • Descrizione (facoltativa).
  • Orario di inizio — necessario perché venga renderizzato un qualsiasi link.
  • Orario di fine (predefinito a 1 ora dopo l'inizio).
  • Posizione (facoltativa, testo libero).
  • Colore di sfondo, padding, bordo e raggio del bordo sulla scheda.
  • Sostituzioni del colore/dimensione del titolo dell'evento, e del colore/sfondo condiviso dai tre link.

Esempi

Subject

Save the date: our fall meetup

Ogni progetto con scopo "Evento" parte già con un blocco Aggiungi al calendario, insieme a Link della riunione, Sede e RSVP — vedi Eventi e webinar per lo schema completo, dall'invito al promemoria, di cui questo blocco fa parte. Un club sportivo riutilizza lo stesso blocco settimana dopo settimana per orari di allenamento e partita, così il calendario di ogni famiglia riflette correttamente il programma indipendentemente dal fuso orario in cui si trova — vedi Squadre e club sportivi. Una serie di webinar può inserire questo blocco in un'email di conferma inviata subito dopo la registrazione, così il destinatario lo aggiunge al proprio calendario nello stesso momento in cui si è iscritto, invece di affidarsi al fatto che se lo ricordi più tardi.

Come appare il fallback statico

<div style="margin:12px 0;background-color:transparent">
  <p style="margin:0 0 8px;font-weight:600;font-size:16px;color:#111827">Q3 Product Launch</p>
  <a href="https://mailinapp.com/api/calendar?d=eyJ0aXRsZSI6...&s=abc123..."
     style="display:inline-block;padding:10px 20px;background-color:#4f46e5;color:#ffffff;
            border-radius:6px;text-decoration:none;font-size:14px;font-weight:600;margin:0 8px 8px 0">
    Download .ics
  </a>
  <a href="https://calendar.google.com/calendar/render?action=TEMPLATE&text=Q3+Product+Launch&dates=20260901T170000Z%2F20260901T180000Z"
     style="display:inline-block;padding:10px 20px;background-color:#4f46e5;color:#ffffff;
            border-radius:6px;text-decoration:none;font-size:14px;font-weight:600;margin:0 8px 8px 0">
    Add to Google Calendar
  </a>
</div>

Questo è l'intero blocco inviato via email — tre link semplici (il terzo, Outlook.com, omesso qui per brevità) costruiti a partire dagli stessi dettagli dell'evento, senza alcuna immagine o contenuto sottoposto a controllo.

Vedi anche