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

Czym jest kod?

Code umożliwia wykonywanie niestandardowych funkcji w odpowiedzi na zdarzenia rejestrowane w Klaviyo. Możesz pisać własne funkcje w języku JavaScript lub Python w edytorze Code, a następnie będą 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ń.

Tematy

Z poniższymi wyjątkami Kod umożliwia wykonywanie niestandardowych funkcji w odpowiedzi na zdarzenia, które można wyszukiwać 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 (tzn. zdarzenia z integracji własnych utworzonych przez Klaviyo)
• Zdarzenia API (tj. zdarzenia zsynchronizowane przez interfejsy API Klaviyo)

Nadawanie uprawnień

Gdy po raz pierwszy uzyskasz dostęp do Code, pojawi się prośba o autoryzację aplikacji Code OAuth. Dzięki temu Twoje funkcje Code mogą uzyskiwać dostęp do danych na Twoim koncie Klaviyo.

Gdy udzielisz dostępu, wracasz do Code. Jeśli pojawi się potwierdzenie konfiguracji, kliknij Odrzuć, aby kontynuować.

Utwórz funkcję

1. Przejdź do Zarządzanie danymi > Kod.
2. Kliknij Rozpocznij, jeśli nie utworzyłeś(-aś) jeszcze funkcji, lub Utwórz funkcję, jeśli masz już funkcje.

3. Na stronie Recipes wybierz gotowy przepis, Blank Python Function lub Blank Node.js Function.

4. Jeśli wybierzesz gotowy przepis, przejrzyj jego kod i instrukcje, a następnie kliknij Wybierz, aby kontynuować.

5. W kroku Szczegóły skonfiguruj swoją funkcję:
   • Nazwij funkcję
     Nazwa służąca do zidentyfikowania funkcji.
   • Wybierz wyzwalacz
     Zdarzenie, które uruchomi wykonanie twojego kodu.
   • Sprawdź Runtime
     Runtime jest ustawiany automatycznie przez pustą funkcję lub przepis, które wybrałeś(-aś): Python lub Node.js.

6. Kliknij Utwórz funkcję. Funkcja otwiera się z następującymi kartami:

• Edytor
• Test
• Dzienniki

Edytor

Na stronie Edytor w Code zobaczysz podział strony na 3 karty:

• 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żesz użyć do pisania funkcji w Pythonie lub JavaScripcie. Są one wykonywane w odpowiedzi na wybrany temat.

Parametry funkcji obsługi

Zachowaj strukturę punktu wejścia udostępnioną przez pustą funkcję lub przepis. W Pythonie użyj funkcji o nazwie handler. W JavaScripcie użyj funkcji eksportowanej jako domyślna. Obie przyjmują 2 parametry:

• Zdarzenie
  Zawiera dane wyzwalającego zdarzenia w formacie JSON:API. W przypadku niestandardowych działań w sekwencjach z wyzwalaczem innym niż zdarzenie (np. Added to List) ten parametr ma wartość None w Pythonie lub null w JavaScripcie.
• Kontekst
  Zawiera dodatkowe metadane dotyczące wykonania funkcji, w tym profil powiązany z wywołaniem funkcji. Możesz uzyskać dostęp do obiektu profilu 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).

1. Na karcie Moduły kliknij Dodaj moduł. Jeśli moduły są już zainstalowane, kliknij Dodaj nowy moduł.

2. Wyszukaj moduł. Wybierz wersję, jeśli dostępna jest lista rozwijana wersji, a następnie kliknij Dodaj.

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

from klaviyo_api import KlaviyoAPI
import os

def handler(event, context):
    klaviyo = KlaviyoAPI(api_key=os.getenv("KLAVIYO_API_KEY"))
    print(klaviyo.Metrics.get_metrics())

import klaviyo

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

import { Metrics } from 'klaviyo';

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

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.

1. Na karcie Zmienne środowiskowe kliknij Dodaj zmienną.

2. Wpisz klucz i wartość zmiennej, a następnie kliknij Zapisz.

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

Test

Karta Test umożliwia uruchomienie Twojej funkcji na podstawie ostatnich zdarzeń oraz sprawdzenie jej dzienników, błędów i alertów.

Aby przetestować funkcję:

1. Otwórz kartę Test i kliknij Uruchom test. Jeśli zdarzenie jest już wybrane, kliknij Zmień zdarzenie, aby wybrać inne.

2. Wybierz zdarzenie, aby uruchomić test. Możesz wybrać maksymalnie 10 ostatnich zdarzeń dla wyzwalacza funkcji z ostatnich 30 dni.

3. Sprawdź dzienniki i wszelkie błędy w panelu „Dane wyjściowe testu”.

Aby ponownie uruchomić funkcję z tym samym zdarzeniem, kliknij Test u góry edytora. Aby użyć innego zdarzenia, kliknij Zmień zdarzenie.

Dzienniki

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

• Status
  Czy wykonanie zostało ukończone czy zakończyło się niepowodzeniem.
• Czas wykonania
  Czas działania funkcji w milisekundach.
• Data
  Znacznik czasu określający, kiedy funkcja została wykonana.

Kliknij identyfikator uruchomienia, aby zobaczyć jego dzienniki. Kliknij Wyświetl wszystkie szczegóły, aby uzyskać więcej informacji o tym wykonaniu.

Limity wykonania

Kod Klaviyo ma następujące limity wykonania:

• Limit czasu funkcji
  Funkcje w Code mogą działać do 15 sekund, zanim upłynie limit czasu.
• Limit szybkości funkcji
  Funkcje w Code umożliwiają maksymalnie 25 jednoczesnych wykonań na funkcję.

Wdrażanie kodu

Po przetestowaniu swojej funkcji wybierz Na żywo z listy rozwijanej statusu, aby ją wdrożyć.

Jeśli wdrożenie się nie powiedzie, sprawdź błąd na karcie Edytor, popraw kod i spróbuj ponownie.

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

Przykładowe rozwiązanie

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

W tym przykładzie zdarzenie niestandardowe Zarezerwowana sesja jest rejestrowane, gdy klient rezerwuje sesję u marki. Funkcja odczytuje właściwości booking_city i booking_postcard_url zdarzenia oraz zapisuje je razem na profilu klienta, aby wykorzystać je w e-mailach kierowanych i segmentacji.

Właściwość profilu Ostatnie rezerwacje przechowuje listę rezerwacji przetworzonych przez funkcję. Ustaw limit na 5, aby zachować pięć ostatnio przetworzonych rezerwacji, przez które możesz iterować w szablonie e-maila.

Kod

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

Przykładowy kod

import os
import klaviyo

def handler(event, context):
    max_properties = int(os.getenv("MAX_PROPERTIES_TO_STORE"))
    profile_id = event["data"]["relationships"]["profile"]["data"]["id"]
    booking_city = event["data"]["attributes"]["event_properties"]["booking_city"]
    booking_postcard_url = event["data"]["attributes"]["event_properties"]["booking_postcard_url"]

    profile = klaviyo.Profiles.get_profiles(filter=f'equals(id,"{profile_id}")')
    current_bookings = profile["data"][0]["attributes"]["properties"].get("Recent bookings", [])

    current_booking = {
        "booking_city": booking_city,
        "booking_postcard_url": booking_postcard_url
    }
    current_bookings.insert(0, current_booking)
    profile_properties = {
      "data": {
        "type": "profile",
        "id": profile_id,
        "attributes": {
          "properties": {"Recent bookings": current_bookings[0:max_properties]}
        }
      }
    }

    klaviyo.Profiles.update_profile(profile_id, profile_properties)

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
  Ustaw Wartość tej zmiennej środowiskowej na 5, aby zachować maksymalnie pięć rezerwacji w Ostatnich rezerwacjach. Kliknij Zapisz.

Testowanie

Podczas tworzenia funkcji służącej do ustawiania danych zdarzeń jako właściwości profilu zakładka Test służy do weryfikacji oczekiwanego wyniku.

Dzienniki

Gdy przetestujesz funkcję i ustawisz ją na Live, karta Logs pokaże wyniki wykonań wywołanych przez zdarzenia Booked shoot.

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 Kod kliknij Rozpocznij, jeśli to Twoja pierwsza funkcja, lub Utwórz funkcję, jeśli masz już funkcje.
2. Wybierz przepis, którego chcesz użyć. Przejrzyj jego kod i instrukcje w podglądzie.
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. Przetestuj funkcję na karcie Test. Gdy potwierdzisz oczekiwany wynik, wybierz Na żywo z menu rozwijanego statusu.

Dodatkowe źródła