Primi passi con Code
Cosa imparerai
Scopri Code e come creare funzioni personalizzate eseguite direttamente da Klaviyo.
Il codice richiede uno sviluppo personalizzato e il team di assistenza di Klaviyo non è in grado di offrire supporto pratico. Se nel tuo team non è presente uno sviluppatore e non te la senti di scrivere il codice in autonomia, valuta la possibilità di rivolgerti a un partner Klaviyo per ricevere assistenza.
Prima di iniziare
Advanced Klaviyo Data Platform non è incluso nell'applicazione di marketing standard di Klaviyo e per accedere alle funzionalità associate è necessario un abbonamento. Vai alla nostra guida alla fatturazione per scoprire come acquistare questo piano.
Cos’è il codice?
Il codice ti consente di eseguire funzioni personalizzate in risposta agli eventi acquisiti in Klaviyo. Puoi scrivere le tue funzioni in Javascript o Python nell'editor del codice, che verranno poi eseguite direttamente nella piattaforma.
Con il codice, puoi inviare dati ai sistemi esterni senza dover impostare un endpoint HTTP pubblico per ricevere webhook e costruire funzionalità personalizzate che si attivano in risposta al verificarsi di un evento. Inoltre puoi accedere a molti moduli precostituiti per facilitare la creazione di soluzioni personalizzate.
Argomenti
Il codice ti consente di eseguire funzioni personalizzate in risposta a qualsiasi evento che può essere interrogato tramite la Get Events API.
Tra questi rientrano:
- Eventi e-mail (ad esempio, e-mail cliccate, e-mail contrassegnate come spam)
- Eventi SMS (ad esempio SMS inviato, SMS ricevuto)
- Eventi notifiche push (ad esempio, push ricevuta, push rimbalzata)
- Eventi dalle integrazioni (ovvero, eventi dalle integrazioni first-party create da Klaviyo)
- Eventi API (cioè gli eventi sincronizzati tramite l'API di Klaviyo)
Klaviyo Code non supporta i seguenti eventi come argomenti:
- E-mail aperta
- E-mail ricevuta
Interfaccia del codice
Per accedere al Codice, vai alla scheda Codice in Advanced Klaviyo Data Platform > gestione dei dati > Codice.
Per creare una funzione personalizzata, seleziona il pulsante Crea una funzione :
Verrai indirizzato alla pagina Ricette , dove puoi selezionare una soluzione predefinita da eseguire oppure una funzione Python o Node.js vuota.
Se selezioni una ricetta esistente, vedrai l’editor del codice con il codice della soluzione, insieme a una descrizione della funzionalità.
Se selezioni una funzione vuota per creare soluzioni personalizzate, verrà visualizzata la finestra modale Dettagli, in cui puoi:
- Assegna un nome alla funzione
Un nome per identificare la funzione. - Seleziona un argomento per la tua funzione
L’evento che attiverà l’esecuzione del codice. - Seleziona un runtime
L'ambiente di runtime in cui viene eseguito il codice (ad es. Python o Node.js).
Dopo aver effettuato le selezioni richieste e aver selezionato il pulsante Crea funzione , verrai portato in un’interfaccia con le seguenti schede:
- Editor
- Risultato del test
- Registri
Concessione delle autorizzazioni
La prima volta che crei una funzione tramite Code, ti verrà chiesto di autenticare l'applicazione OAuth di Code. Questo è necessario affinché le funzioni Code possano accedere ai dati nel tuo account Klaviyo.
Dopo aver concesso l’accesso, verrai indirizzato all’editor di codice.
Editor
Nella pagina Editor in Code, vedrai la pagina divisa in 3 schede:
- Codice
La scheda Codice include un editor in cui puoi scrivere funzioni Python o Javascript. - Moduli
I moduli sono pacchetti di terze parti che aggiungono funzionalità alle tue funzioni. - Variabili d'ambiente
Le variabili d'ambiente sono le coppie chiave-valore a cui la funzione accede durante l'esecuzione.
Codice
Nella scheda Codice vedrai un editor che puoi usare per scrivere funzioni Python o Javascript, che vengono eseguite in risposta all’argomento selezionato.
Parametri della funzione handler
Affinché Klaviyo possa eseguire il codice che scrivi, devi racchiuderlo in una funzione denominata “handler” che accetta 2 parametri:
- Evento
È composto dai dati dell'evento associati all'evento di attivazione in formato JSON:API. Se l'attivatore non è basato su un evento (ad es. Aggiunto all'elenco), il valore di questo parametro sarà Nessuno o Null a seconda del linguaggio. - Contesto
Contiene metadati aggiuntivi sull’esecuzione della funzione, incluso il profilo associato all’invocazione della funzione. Puoi accedere all’oggetto profilo tramite context.profile in Javascript o context["profile"] in Python.
Di seguito sono riportati esempi dei parametri event e context che vengono passati alla funzione handler.
Formato dell'evento di esempio
{
{
"data": {
"type": "event",
"id": "7S2q9haejYG",
"attributes": {
"timestamp": 1694435729,
"event_properties": {
"MfaEnabled": false,
"IpAddress": "000.00.0.0",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
"UserRole": "Owner",
"SessionId": "34sh0a9nh8ngnk2nfacjxmt592yx40ib",
"LoginType": "Username_password",
"current_company_id": "XXXXX",
"$event_id": "1694435729"
},
"datetime": "2023-09-11 12:35:29+00:00",
"uuid": "b0b8fe80-509f-11ee-8001-278cc529fcd3"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "123456"
},
"links": {
"self": "https://a.klaviyo.com/api/events/7S2q9haejYG/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/7S2q9haejYG/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "4Tdup6"
},
"links": {
"self": "https://a.klaviyo.com/api/events/7S2q9haejYG/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/7S2q9haejYG/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/7S2q9haejYG/"
}
}
}Formato del contesto di esempio
{
"company_id": "XXXXX",
"trigger": {"type": "event", "uid": "123456"},
"function_id": "123456",
}Moduli
Nella scheda Moduli, puoi scegliere tra i moduli predefiniti più popolari (ad es., pacchetti di terze parti che aggiungono funzionalità alle tue funzioni).
Per aggiungere un modulo esterno da usare nel tuo codice, seleziona il pulsante Aggiungi modulo:
Nella finestra modale che appare, puoi cercare e selezionare il modulo che vuoi aggiungere:
Una volta aggiunto, puoi usare il modulo con il codice che scrivi in Klaviyo.
Dovresti fare riferimento alla documentazione nativa del modulo esterno per informazioni su come utilizzarlo.
Il modulo klaviyo
Tutte le funzioni di Codice includono un pacchetto Klaviyo personalizzato già preinstallato nel tuo ambiente Codice. Questo modulo consente alle tue funzioni di accedere ai dati nel tuo account Klaviyo senza dover fornire credenziali, come una chiave API.
L’API del modulo Klaviyo dipende dal fatto che il tuo codice sia scritto in Python o Javascript.
Python Klaviyo module
L’API del modulo klaviyo preinstallato è la stessa dell’oggetto SDK di Klaviyo che normalmente creeresti con il modulo Python klaviyo-api. Puoi considerare il modulo Klaviyo come un client SDK Klaviyo preistanziato.
Ad esempio, in un flusso di lavoro tradizionale, per prima cosa istanzieresti un nuovo client SDK di Klaviyo passando una chiave API al costruttore, quindi utilizzeresti l’oggetto SDK risultante.
from klaviyo_api import KlaviyoAPIimport osdef handler(event, context): klaviyo = KlaviyoAPI(api_key=os.getenv("KLAVIYO_API_KEY")) print(klaviyo.Metrics.get_metrics())Con Code, ti basta importare l'oggetto Klaviyo e l'autenticazione viene gestita automaticamente per te.
import klaviyodef handler(event, context): print(klaviyo.Metrics.get_metrics())Visualizza gli oggetti Klaviyo disponibili e i relativi metodi.
Javascript Klaviyo module
Quando usi il modulo Klaviyo preinstallato nelle tue funzioni Javascript, importa le funzionalità specifiche a cui vuoi accedere usando la sintassi con parentesi graffe dal modulo Klaviyo. Poi usale come faresti normalmente con un oggetto API usando il modulo Javascript klaviyo-api .
import { Metrics } from 'klaviyo';export default async (event, context) => { console.log(await Metrics.getMetrics())}Visualizza gli oggetti Klaviyo disponibili e i relativi metodi.
Variabili d'ambiente
La scheda Variabili d'ambiente ti consente di impostare accoppiamenti chiave-valore a cui il tuo codice in Klaviyo può fare riferimento durante l'esecuzione. Possono essere utilizzate per memorizzare informazioni come credenziali e chiavi segrete, in modo che le tue funzioni possano accedervi durante l'esecuzione.
Per aggiungere una variabile di ambiente, seleziona il pulsante Aggiungi una variabile:
Nella finestra modale che appare, puoi impostare una coppia chiave-valore per la variabile di ambiente.
Una volta create, le variabili d’ambiente saranno elencate nella pagina e potranno essere utilizzate nel codice.
Per accedere alle variabili di ambiente nel tuo codice, usa os.getenv("Key") per Python o process.env.KEY per Node.js.
Per aggiornare il valore di una variabile di ambiente esistente, devi creare una nuova variabile con la stessa chiave per cui vuoi aggiornare il valore.
Risultato del test
La scheda Test output in Code ti consente di testare il tuo codice con eventi recenti per confermare che l'output si comporti come previsto.
Per testare la funzione:
- Seleziona il pulsante Esegui test:
- Nella finestra modale che appare, seleziona un evento con cui eseguire il test. Puoi selezionare uno dei 10 eventi più recenti acquisiti in Klaviyo.
- Dopo aver selezionato un evento con cui eseguire il test, verrà mostrato l’output del test:
Registri
La scheda Log mostra lo stato di integrità delle funzioni Code in esecuzione. Vedrai:
- Stato
Lo stato di avanzamento dell’esecuzione di una funzione. - Tempo di risposta
Il tempo necessario affinché il tuo codice venga eseguito in risposta a un evento. - Data
Un timestamp che indica quando la funzione è stata eseguita.
Limiti tariffari
Il codice di Klaviyo ha i seguenti limiti di frequenza:
- Timeout della funzione
Le funzioni in Code possono essere eseguite per un massimo di 15 secondi prima di andare in timeout. - Limite di frequenza della funzione
Le funzioni in Code consentono fino a 25 esecuzioni concorrenti per funzione.
Distribuzione del codice
Per distribuire il codice che scrivi nell’editor, imposta il menu a discesa dello stato su Live.
Una volta pubblicato, il codice che scrivi verrà eseguito ogni volta che l'evento dell'argomento viene acquisito in Klaviyo.
Quando una funzione viene impostata come attiva, potrebbe verificarsi un ritardo fino a 15 minuti prima che gli eventi inizino ad attivare la funzione.
Soluzione di esempio
Di seguito è riportato un esempio di soluzione personalizzata implementata con codice.
Nell’esempio, i dati dell’evento sono impostati come Proprietà del profilo, così possono essere usati nelle e-mail mirate e nella segmentazione. L'evento personalizzato Booked shoot viene acquisito in Klaviyo quando i clienti prenotano un servizio fotografico con il brand e i dati sulla città della prenotazione e l'URL associato vengono impostati come Proprietà del profilo sul rispettivo profilo.
Viene anche creata una proprietà chiamata Recent bookings , che memorizza i dati dei 5 eventi Booked shoot più recenti, in modo da poterli scorrere in ciclo e accedervi nei modelli di e-mail.
Codice
Il codice Python per questa soluzione è scritto nell'editor di codice e viene eseguito direttamente da Klaviyo.
Codice di esempio
Moduli
In questo esempio, viene usato il modulo Klaviyo integrato. Il modulo Klaviyo si basa sull’aggiunta del modulo klaviyo-api alla funzione. Una volta aggiunto, il modulo Klaviyo gestirà l'autenticazione per te, quindi non è necessaria alcuna chiave API.
Variabili d'ambiente
Le variabili d'ambiente possono essere utilizzate per memorizzare informazioni come credenziali e chiavi segrete, in modo che le tue funzioni possano accedervi durante l'esecuzione. Per questo esempio, è impostato il seguente accoppiamento chiave-valore:
- MAX_PROPERTIES_TO_STORE
Una variabile d’ambiente utilizzata per definire il numero massimo di proprietà da archiviare per la funzione di esempio.
Esecuzione di test
Durante la creazione della funzione per impostare i dati dell'evento come Proprietà del profilo, la scheda Output di test viene utilizzata per verificare l'output previsto.
Registri
Una volta che la funzione è stata creata e testata, la scheda Log mostra lo stato di integrità della funzione mentre viene eseguita in risposta agli eventi Shooting prenotato .
Risultato
Con questa funzione di codice attiva, quando i clienti si iscrivono agli shooting e attivano l’evento personalizzato Shooting prenotato, i dati dell’evento verranno archiviati nel profilo del cliente per essere utilizzati nella segmentazione e nelle campagne mirate.
Implementazione delle ricette
Le ricette in Code ti consentono di implementare soluzioni predefinite senza bisogno di sviluppo personalizzato.
Per implementare una Recipe nel tuo account Klaviyo:
- Seleziona il pulsante Crea funzione nella pagina Codice.
- Scegli la Recipe che vuoi implementare nel tuo account. Verrai indirizzato all'editor, dove potrai vedere il codice della Recipe selezionata, insieme a una descrizione di ciò che fa la funzione.
- Fai clic sul pulsante Seleziona per continuare.
- Scegli un nome per la funzione e il trigger che ne causerà l'esecuzione. Il runtime viene impostato automaticamente in base al codice della Recipe.
- Seleziona il pulsante Crea funzione.
- Una volta creata la funzione, imposta le variabili di ambiente pertinenti in modo che la funzione abbia i dati necessari per essere eseguita.
- Ora puoi testare la Recipe e impostarla su Live.
Le ricette potrebbero richiedere l’aggiornamento di alcuni campi per farli corrispondere alle preferenze di denominazione desiderate e ai dati nei tuoi eventi. Consulta le istruzioni per la Recipe per vedere quali campi possono essere rinominati e modificati.
Risorse aggiuntive
- Getting started with Advanced KDP
Learn more about using Advanced KDP (Klaviyo data platform) to gather robust customer insights across all your marketing initiatives. Advanced KDP enables more advanced data management, manipulation, and analysis. It also provides actionable strategies to employ across each of your individual audiences and your business as a whole.
- Understand the different webhooks available in Klaviyo
Learn about the differences between webhook solutions available in Klaviyo, and when you should use each one.