Pierwsze kroki z Code

Czego się dowiesz?

Dowiedz się więcej o Code i o tym, jak tworzyć niestandardowe funkcje wykonywane bezpośrednio przez Klaviyo.

Kod wymaga niestandardowego opracowania, a zespół pomocy Klaviyo nie jest w stanie zaoferować praktycznego wsparcia. Jeśli nie masz w zespole programisty i nie czujesz się komfortowo, pisząc kod samodzielnie, rozważ skontaktowanie się z partnerem Klaviyo w celu uzyskania pomocy.

Kilka słów na początek

Zaawansowana platforma danych klientów Klaviyo nie wchodzi w skład standardowej aplikacji marketingowej Klaviyo, a dostęp do powiązanych z nią funkcji wymaga subskrypcji. Przejdź do naszego przewodnika rozliczeń, aby dowiedzieć się, jak kupić ten plan.

Czym jest kod?

Kod umożliwia wykonywanie niestandardowych funkcji w odpowiedzi na zdarzenia rejestrowane w Klaviyo. W edytorze Code można napisać własne funkcje w Javascript lub Python, a następnie są one wykonywane bezpośrednio na platformie.

Kod umożliwia wysyłanie danych do zewnętrznych systemów bez konieczności konfigurowania publicznego punktu końcowego HTTP na potrzeby odbierania elementów webhook. Pozwala też tworzyć niestandardowe funkcje, które są uruchamiane w reakcji na wystąpienie danego zdarzenia. Można także uzyskać dostęp do wielu popularnych gotowych modułów, co ułatwia tworzenie niestandardowych rozwiązań.

Dowiedz się jak tworzyć niestandardowe funkcje za pomocą kodu.

Tematy

Kod umożliwia wykonywanie niestandardowych funkcji w odpowiedzi na dowolne zdarzenie, które można wyszukać za pomocą API Get Events.

Należą do nich:

• Zdarzenia e-mail (np. Kliknięto e-mail, Oznaczono e-mail jako spam )
• Zdarzenia SMS (np. Wysłano SMS, Odebrano SMS)
• Zdarzenia powiadomień push (np. Odebrano push, Odrzucono push)
• Zdarzenia z integracji (tj. zdarzenia z integracji pierwszej strony utworzonych przez Klaviyo)
• Zdarzenia API (tj. zdarzenia zsynchronizowane przez interfejsy API Klaviyo)

Klaviyo Code nie obsługuje następujących zdarzeń jako tematów:

1. Otwarto e-mail
2. Otrzymany e-mail

Interfejs kodu

Aby uzyskać dostęp do sekcji Kod, przejdź do karty Kod w obszarze Zaawansowana platforma danych klientów Klaviyo > Zarządzanie danymi > Kod.

Aby utworzyć funkcję niestandardową, wybierz przycisk Utwórz funkcję :

Zostaniesz przeniesiony(-a) na stronę Przepisy , gdzie możesz wybrać gotowe rozwiązanie do uruchomienia lub pustą funkcję w Pythonie albo Node.js.

Jeśli wybierzesz istniejący przepis, zobaczysz edytor kodu z kodem rozwiązania oraz opisem funkcjonalności.

Jeśli wybierzesz pustą funkcję, aby utworzyć własne rozwiązania niestandardowe, pojawi się okno modalne Szczegóły, w którym możesz:

• Nazwij funkcję Nazwa służąca do zidentyfikowania funkcji.
• Wybierz temat dla funkcji Zdarzenie, które uruchomi wykonanie kodu.
• Wybierz środowisko wykonawcze Środowisko wykonawcze, w którym uruchamiany jest kod (tj. Python lub Node.js).
  

  Po dokonaniu wymaganych wyborów i wybraniu przycisku Utwórz funkcję zostanie wyświetlony interfejs z następującymi kartami:

• Edytor
• Wyniki testu
• Dzienniki

Nadawanie uprawnień

Gdy po raz pierwszy utworzysz funkcję za pomocą Code, pojawi się prośba o uwierzytelnienie aplikacji Code OAuth. Jest to wymagane, aby funkcje Code mogły uzyskać dostęp do danych na koncie Klaviyo.

Po przyznaniu dostępu zostaniesz przeniesiony(-a) do edytora kodu.

Edytor

Na stronie Editor w Code zobaczysz stronę podzieloną na 3 zakładki:

• Kod
  Karta Kod ma edytor, w którym możesz pisać funkcje w Pythonie lub JavaScripcie.
• Moduły Moduły to pakiety innych firm, które dodają funkcjonalność do funkcji.
• Zmienne środowiskowe Zmienne środowiskowe to pary kluczy i wartości, do których funkcja uzyskuje dostęp podczas działania.

Kod

Na karcie Kod zobaczysz edytor, którego można użyć do pisania funkcji w języku Python lub Javascript, które są wykonywane w odpowiedzi na wybrany temat.

Parametry funkcji obsługi

Aby Klaviyo mogło wykonać napisany kod, musi on być opakowany w funkcję o nazwie „handler”, która przyjmuje 2 parametry:

• Zdarzenie Składa się z danych zdarzenia powiązanych ze zdarzeniem wyzwalającym w formacie JSON:API. Jeśli wyzwalacz nie jest oparty na zdarzeniu (np. Dodano do listy), wartością tego parametru będzie None lub Null w zależności od języka.
• Kontekst Zawiera dodatkowe metadane dotyczące wykonania funkcji, w tym profil powiązany z wywołaniem funkcji. Dostęp do obiektu profilu można uzyskać przez context.profile w Javascript lub context["profile"] w Pythonie.

Poniżej znajdują się przykłady parametrów zdarzenia i kontekstu, które są przekazywane do funkcji obsługi.

Przykładowy format zdarzenia

{
    {
  "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/"
    }
  }
}

Przykładowy format kontekstu

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

Moduły

Na karcie Moduły możesz wybierać spośród najpopularniejszych gotowych modułów (tj. pakietów firm trzecich, które dodają możliwości do Twoich funkcji).

Aby dodać zewnętrzny moduł do użycia w kodzie, wybierz przycisk Dodaj moduł:

W wyświetlonym oknie modalnym możesz wyszukać i wybrać moduł, który chcesz dodać:

Po dodaniu możesz używać modułu z kodem, który napiszesz w Klaviyo.

Aby uzyskać informacje o tym, jak go używać, zapoznaj się z natywną dokumentacją zewnętrznego modułu.

Moduł Klaviyo

Wszystkie funkcje Code zawierają niestandardowy pakiet Klaviyo, który jest wstępnie zainstalowany w środowisku Code. Ten moduł umożliwia funkcjom dostęp do danych na koncie Klaviyo bez konieczności podawania jakichkolwiek poświadczeń, takich jak klucz API.

API modułu Klaviyo zależy od tego, czy kod jest napisany w Pythonie czy Javascript.

Python Klaviyo module

API wstępnie zainstalowanego modułu klaviyo jest takie samo jak obiekt zestawu SDK Klaviyo, który zwykle jest tworzony za pomocą modułu Python klaviyo-api. Moduł klaviyo można traktować jako wstępnie zainicjowanego klienta zestawu SDK klaviyo.

Na przykład w tradycyjnej organizacji pracy najpierw utworzysz nowego klienta zestawu SDK Klaviyo, przekazując klucz API do konstruktora, a następnie użyjesz otrzymanego obiektu zestawu SDK.

from klaviyo_api import KlaviyoAPIimport osdef handler(event, context):  klaviyo = KlaviyoAPI(api_key=os.getenv("KLAVIYO_API_KEY"))  print(klaviyo.Metrics.get_metrics())

W Code wystarczy zaimportować obiekt Klaviyo, a uwierzytelnianie zostanie obsłużone za Ciebie.

import klaviyodef handler(event, context):  print(klaviyo.Metrics.get_metrics())

Wyświetl dostępne obiekty Klaviyo i ich metody.

Javascript Klaviyo module

Gdy używasz wstępnie zainstalowanego modułu klaviyo w swoich funkcjach JavaScript, zaimportuj konkretne funkcje Klaviyo, do których chcesz uzyskać dostęp, używając składni z nawiasami klamrowymi z modułu klaviyo. Następnie użyj ich tak jak zwykle obiektu API, używając modułu Javascriptklaviyo-api .

import { Metrics } from 'klaviyo';export default async (event, context) => {  console.log(await Metrics.getMetrics())}

Wyświetl dostępne obiekty Klaviyo i ich metody.

Zmienne środowiskowe

Karta Environment variables umożliwia ustawienie par klucz-wartość, do których może odwoływać się kod w Klaviyo podczas działania. Można ich używać do przechowywania informacji, takich jak poświadczenia i klucze tajne, aby funkcje miały do nich dostęp podczas działania.

Aby dodać zmienną środowiskową, wybierz przycisk Dodaj zmienną:

W wyświetlonym oknie modalnym możesz ustawić parę klucz–wartość dla zmiennej środowiskowej.

Po utworzeniu zmienne środowiskowe będą widoczne na liście na stronie i będzie można używać ich w kodzie.

Aby uzyskać dostęp do zmiennych środowiskowych w kodzie, użyj os.getenv("Key") dla Pythona lub process.env.KEY dla Node.js.

Aby zaktualizować wartość istniejącej zmiennej środowiskowej, musisz utworzyć nową zmienną z tym samym kluczem, którego wartości chcesz dokonać aktualizacji.

Wyniki testu

Karta Dane wyjściowe testu w sekcji Kod pozwala testować kod z użyciem ostatnich zdarzeń, aby potwierdzić, że dane wyjściowe działają zgodnie z oczekiwaniami.

Aby przetestować funkcję:

1. Wybierz przycisk Uruchom test:
   
2. W wyświetlonym oknie modalnym wybierz zdarzenie, które chcesz przetestować. Możesz wybrać jedno z 10 najnowszych zdarzeń zarejestrowanych w Klaviyo.
   
3. Po wybraniu zdarzenia do testowania zostaną wyświetlone wyniki testu:

Dzienniki

Karta Dzienniki pokazuje kondycję Twoich bieżących funkcji kodu. Zobaczysz:

• Status Postęp wykonywania funkcji.
• Czas odpowiedzi Ilość czasu potrzebna na wykonanie kodu w odpowiedzi na zdarzenie.
• Data Znacznik czasu określający, kiedy funkcja została wykonana.

Limity częstotliwości

Kod Klaviyo ma następujące limity szybkości:

• Przekroczenie limitu czasu funkcji Funkcje w Code mogą być wykonywane przez maksymalnie 15 sekund, zanim przekroczą limit czasu.
• Limit szybkości funkcji Funkcje w Code umożliwiają maksymalnie 25 jednoczesnych wykonań na funkcję.

Wdrażanie kodu

Aby wdrożyć kod napisany w edytorze, przełącz menu rozwijane stanu na Na żywo.

Po ustawieniu jako aktywny kod, który napiszesz, będzie wykonywany za każdym razem, gdy zdarzenie tematu zostanie zarejestrowane w Klaviyo.

Gdy funkcja zostanie uruchomiona, może wystąpić opóźnienie do 15 minut, zanim zdarzenia zaczną ją wyzwalać.

Przykładowe rozwiązanie

Poniżej znajduje się przykład wdrożenia niestandardowego rozwiązania za pomocą Kodu.

W przykładzie dane zdarzenia są ustawione jako właściwości profilu, aby można było ich używać w e-mailach kierowanych i w segmentacji. Niestandardowe zdarzenie Booked shoot jest rejestrowane w Klaviyo, gdy klienci rezerwują sesję zdjęciową u marki, a dane o mieście rezerwacji i powiązanym adresie URL są ustawiane jako właściwości profilu w odpowiednim profilu.

Tworzona jest też właściwość o nazwie Ostatnie rezerwacje , która przechowuje dane z 5 najnowszych zdarzeń Zarezerwowana sesja, aby można było je zapętlać i uzyskiwać do nich dostęp w szablonach e-mail.

Kod

Kod Python dla tego rozwiązania jest napisany w edytorze kodu i jest wykonywany bezpośrednio przez Klaviyo.

Przykładowy kod

Moduły

W tym przykładzie używany jest wbudowany moduł Klaviyo. Moduł Klaviyo opiera się na tym, że do funkcji dodano moduł klaviyo-api. Po dodaniu moduł Klaviyo zajmie się uwierzytelnianiem, więc nie jest potrzebny klucz API.

Zmienne środowiskowe

Zmienne środowiskowe mogą służyć do przechowywania informacji, takich jak dane uwierzytelniające i tajne klucze, aby funkcje mogły uzyskać do nich dostęp podczas działania. W tym przykładzie ustawiona jest następująca para klucz-wartość:

• MAX_PROPERTIES_TO_STORE Zmienna środowiskowa używana do określenia maksymalnej liczby właściwości do przechowywania dla przykładowej funkcji.

Testowanie

Podczas tworzenia funkcji ustawiającej dane zdarzenia jako właściwości profilu, karta Dane wyjściowe testu służy do weryfikacji oczekiwanego wyniku.

Dzienniki

Po utworzeniu i przetestowaniu funkcji karta Logi pokazuje stan kondycji funkcji w trakcie jej wykonywania w odpowiedzi na zdarzenia Zarezerwowana sesja .

Rezultat

Dzięki tej funkcji kodu, gdy klienci rejestrują się na sesje i wyzwalają niestandardowe zdarzenie Zarezerwowana sesja, dane zdarzenia będą zapisywane w profilu klienta do wykorzystania w segmentacji i kampaniach kierowanych.

Wdrażanie receptur 

Receptury w Code pozwalają wdrażać gotowe rozwiązania bez potrzeby niestandardowego programowania.

Aby wdrożyć przepis na swoim koncie Klaviyo:

1. Na stronie Code wybierz przycisk Create function.
2. Wybierz przepis, który chcesz wdrożyć na swoim koncie. Nastąpi przekierowanie do edytora, w którym można zobaczyć kod dla wybranego przepisu, wraz z opisem działania funkcji.
3. Kliknij przycisk Wybierz, aby kontynuować.
   
4. Wybierz nazwę funkcji oraz wyzwalacz, który spowoduje jej uruchomienie. Środowisko uruchomieniowe jest ustawiane automatycznie na podstawie kodu dla receptury.
5. Wybierz przycisk Utwórz funkcję.
6. Gdy funkcja zostanie utworzona, ustaw odpowiednie zmienne środowiskowe, aby miała dane potrzebne do działania.
7. Teraz można przetestować Recipe i ustawić jako Live.

Przepisy mogą wymagać zaktualizowania określonych pól, aby pasowały do preferowanego nazewnictwa oraz danych w zdarzeniach. Zapoznaj się z instrukcjami dotyczącymi przepisu, aby sprawdzić, które pola można zmieniać i edytować.