Iniziare con il Codice

Imparerai

Impari a conoscere il Codice e a creare funzioni personalizzate che vengono eseguite direttamente da Klaviyo.

Il codice richiede uno sviluppo personalizzato e il team di assistenza di Klaviyo non è in grado di offrire assistenza pratica. Se non ha uno sviluppatore nel suo team e non si sente a suo agio nello scrivere codice da solo, consideri di rivolgersi a un Partner Klaviyo per ricevere assistenza.

Prima di iniziare

Che cos'è il Codice?

Il codice le consente di eseguire funzioni personalizzate in risposta agli eventi acquisiti in Klaviyo. Può scrivere le sue funzioni Javascript o Python nell'editor di codice, che vengono 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 le consente di eseguire funzioni personalizzate in risposta a qualsiasi evento che può essere interrogato tramite l'API Get Events.

Questi includono:

• Eventi e-mail (ad esempio, e-mail cliccate, e-mail contrassegnate come spam)
• Eventi SMS (ad esempio, SMS inviati, SMS ricevuti)
• Eventi notifiche push (ad esempio, push ricevuta, push rimbalzata)
• Eventi da integrazioni (cioè eventi da integrazioni di prima parte create da Klaviyo)
• Eventi API (cioè gli eventi sincronizzati tramite l'API di Klaviyo)

Interfaccia del codice

Per accedere al Codice, vai alla scheda Codice in Advanced KDP > gestione dei dati > Codice. 

Per creare una funzione personalizzata, selezioni il pulsante Crea una funzione :

Verrà portato alla pagina Ricette , dove potrà selezionare una soluzione precostituita da eseguire, oppure una funzione Python o Node.js vuota.

Se seleziona una ricetta esistente, vedrà l'editor di codice con il codice della soluzione, insieme ad una descrizione della funzionalità. 

Se seleziona una funzione vuota, in modo da poter creare le sue soluzioni personalizzate, apparirà la maschera Dettagli dove potrà farlo:

• Nome della sua funzione
  Un nome per identificare la sua funzione.
• Selezioni un argomento per la sua funzione
  L'evento che attiverà l'esecuzione del suo codice .
• Selezionare un runtime
  L'ambiente di runtime in cui viene eseguito il codice (ad esempio, Python o Node.js).

Dopo aver effettuato le selezioni necessarie e aver selezionato il pulsante Crea funzione , si aprirà un'interfaccia con le seguenti schede: 

• Editore 
• Uscita del test 
• Diari

Concessione di permessi

La prima volta che crei una funzione tramite Code, ti verrà richiesto di autenticare l'applicazione Code OAuth. Questo è necessario affinché le funzioni del tuo Codice possano accedere ai dati del tuo account Klaviyo.

Una volta concesso l'accesso, verrai portato nell'editor del codice.

Editore

Nella pagina Editor in Codice, la pagina è suddivisa in 3 schede:

• Codice
  La scheda Codice contiene un editor in cui può scrivere funzioni Python o Javascript.
• Moduli
  I moduli sono pacchetti di terze parti che aggiungono funzionalità alle sue funzioni.
• Variabili d'ambiente
  Le variabili d'ambiente sono le coppie chiave-valore a cui la sua funzione accede quando viene eseguita. 

Codice

Nella scheda Codice , vedrà un editor che potrà utilizzare per scrivere funzioni Python o Javascript che verranno eseguite in risposta all'argomento selezionato.

Parametri della funzione Handler

Affinché Klaviyo esegua il codice che scrivi, questo deve essere racchiuso in una funzione chiamata "handler" che accetta 2 parametri:

• Evento
  Consiste nei dati dell'evento associati all'evento scatenante in formato JSON:API. Se il trigger non è basato su un evento (ad esempio, Aggiunto all'elenco), il valore di questo parametro sarà None o Null a seconda della lingua.
• Contesto
  Contiene metadati aggiuntivi sull'esecuzione della funzione, compreso il profilo associato all'invocazione della funzione. Puoi accedere all'oggetto profilo tramite context.profilo in Javascript o context["profilo" ] in Python.

Di seguito sono riportati alcuni esempi di parametri dell'evento e del contesto che vengono passati alla funzione handler.

Esempio di formato dell'evento

{
    {
  "dati": {
   "tipo": "evento",
   "id": "7S2q9haejYG",
   "attributi": {
     "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"
    },
   "relazioni": {
     "profilo": {
       "dati": {
          "type": "profile",
          "id": "123456"
        },
       "link": {
          "self": "https://a.klaviyo.com/api/events/7S2q9haejYG/relationships/profile/",
          "related": "https://a.klaviyo.com/api/events/7S2q9haejYG/profile/"
        }
      },
      metrico": {
       "dati": {
          "type": "metric",
          "id": "4Tdup6"
        },
       "link": {
          "self": "https://a.klaviyo.com/api/events/7S2q9haejYG/relationships/metric/",
          "related": "https://a.klaviyo.com/api/events/7S2q9haejYG/metric/"
        }
      }
    },
   "link": {
      "self": "https://a.klaviyo.com/api/events/7S2q9haejYG/"
    }
  }
}

Esempio di formato del contesto 

{
   "company_id": "XXXXX",
   "trigger": {"type": "event", "uid": "123456"},
   "function_id": "123456",
}

Moduli

Nella scheda Moduli, può scegliere tra i moduli precostituiti più popolari (cioè pacchetti di terze parti che aggiungono funzionalità alle sue funzioni). 

Per aggiungere un modulo esterno da utilizzare nel suo codice, selezioni il pulsante Aggiungi modulo:

Nella maschera che appare, può cercare e selezionare il modulo che desidera aggiungere: 

Una volta aggiunto, può utilizzare il modulo con il codice che scrive in Klaviyo.

da klaviyo_api importa KlaviyoAPI
importa os
def handler(evento, contesto):
  Klaviyo = KlaviyoAPI(api_key=os.getenv("API"))
  print(Klaviyo.metrica.get_metrics())

importa Klaviyo

def handler(evento, contesto):
  print(Klaviyo.metrica.get_metrics())

importa { Metrics } da 'Klaviyo';
esporta default async (evento, contesto) => {
  console.log(await Metrics.getMetrics())
}

Variabili d'ambiente 

La scheda Variabili d'ambiente le permette di impostare delle coppie chiave-valore che il suo codice in Klaviyo può consultare quando viene eseguito. Questi possono essere utilizzati per memorizzare informazioni come credenziali e chiavi segrete, in modo che le sue funzioni possano accedervi durante l'esecuzione. 

Per aggiungere una variabile d'ambiente, selezioni il pulsante Aggiungi una variabile: 

Nella maschera che appare, può impostare una coppia chiave-valore per la sua variabile d'ambiente. 

Una volta create, le variabili d'ambiente saranno elencate nella pagina e potranno essere utilizzate nel suo codice. 

Uscita del test

La scheda Test output in Codice le permette di testare il suo codice con eventi recenti per confermare che l'output si comporta come previsto. 

Per testare la sua funzione:

1. Seleziona il pulsante Esegui test:
   
2. Nella maschera che appare, selezioni un evento da testare. Può selezionare tra i 10 eventi più recenti catturati in Klaviyo.
   
3. Dopo aver selezionato un evento da testare, verrà mostrato l'output del test:

Diari

La scheda Registri mostra lo stato di salute delle funzioni del suo Codice in corso. Vedrà:

• Stato
  Il progresso dell'esecuzione di una funzione. 
• Tempo di risposta
  La quantità di tempo necessaria al suo codice per essere eseguito in risposta a un evento.
• Data
  Un timestamp per il momento in cui la funzione è stata eseguita. 

Limiti tariffari

Il codice Klaviyo ha i seguenti limiti di velocità:

• Timeout delle funzioni
  Le funzioni del Codice possono essere eseguite per un massimo di 15 secondi prima di andare in timeout.
• Limite di velocità delle funzioni
  Le funzioni di Code consentono un massimo di 25 esecuzioni contemporanee per funzione.

Distribuzione del codice 

Per distribuire il codice che scrive nell'editor, deve spostare il menu a tendina dello stato su Live. 

Una volta impostato su live, il codice che lei scrive verrà eseguito ogni volta che l'evento dell'argomento viene catturato in Klaviyo.

Esempio di soluzione

Di seguito è riportato un esempio di soluzione personalizzata implementata con Code.

Nell'esempio, i dati degli eventi sono impostati come proprietà del profilo, in modo da poter essere utilizzati nelle e-mail mirate e nella segmentazione. L'evento personalizzato Servizio prenotato viene catturato in Klaviyo quando i clienti prenotano un servizio fotografico con il marchio, e i dati sulla città di prenotazione e l'URL associato vengono impostati come proprietà del profilo sul rispettivo profilo.

Viene creata anche una proprietà chiamata Prenotazioni recenti , che memorizza i dati dei 5 eventi di tiro prenotati più recenti, in modo da poterli scorrere 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 utilizzato il modulo integrato di Klaviyo. Il modulo Klaviyo si basa sull'aggiunta del modulo Klaviyo-API alla funzione. Una volta aggiunto, il modulo Klaviyo si occuperà dell'autenticazione per te, quindi non è necessaria alcuna chiave API.

Variabili d'ambiente

Le variabili d'ambiente possono essere utilizzate per negoziare informazioni come credenziali e chiavi segrete in modo che le tue funzioni possano accedervi durante l'esecuzione. In questo esempio, viene impostata la seguente coppia chiave-valore:

• MAX_PROPRIETÀ_DA_STORE
  Una variabile d'ambiente utilizzata per definire il numero massimo di proprietà da memorizzare per la funzione di esempio.

Test

Durante la creazione della funzione per impostare i dati degli eventi come proprietà del profilo, la scheda Test output viene utilizzata per verificare l'output previsto.

Diari

Una volta creata e testata la funzione, la scheda Registri mostra lo stato di salute della funzione mentre viene eseguita in risposta agli eventi di ripresa prenotati . 

Risultato

Con questa funzione del Codice, quando i clienti si iscrivono ai servizi fotografici e attivano l'evento personalizzato Servizio prenotato, i dati dell'evento saranno memorizzati nel profilo del cliente per essere utilizzati nella segmentazione e nelle campagne mirate. 

Implementazione delle ricette  

Le Ricette nel Codice le consentono di implementare soluzioni precostituite senza la necessità di uno sviluppo personalizzato.

Per implementare una Ricetta nel suo account Klaviyo:

1. Selezioni il pulsante Crea funzione nella pagina Codice.
2. Scelga la Ricetta che desidera implementare nel suo account. Verrà portato nell'editor dove potrà vedere il codice della Ricetta selezionata, insieme ad una descrizione di ciò che fa la funzione.
3. Clicchi sul pulsante Seleziona per continuare.
   
4. Scelga un nome per la funzione e il trigger che ne causerà l'esecuzione. Il tempo di esecuzione viene impostato automaticamente in base al codice della Ricetta.
5. Selezioni il pulsante della funzione Crea.
6. Una volta creata la funzione, imposti le variabili d'ambiente pertinenti, in modo che la funzione abbia i dati necessari per essere eseguita.
7. La Ricetta può ora essere testata e impostata su Live.

Risorse aggiuntive 

Primi passi con Advanced KDP
Capire i diversi webhook disponibili in Klaviyo