コードのスタートガイド

このページで学べること

Code について、および Klaviyo で直接実行されるカスタム関数の作成方法をご紹介します。

コードにはカスタム開発が必要で、Klaviyo のサポートチームでは実際の作業を直接お手伝いすることはできません。チーム内に開発者がいなく、コードを自身で書くことに不安がある場合は、Klaviyo パートナーにご連絡いただき、サポートのご利用をご検討ください。

始める前に

コードとは？

コードを使用すると、Klaviyoでキャプチャされたイベントに応答してカスタム関数を実行できます。Codeエディターで独自のJavaScriptまたはPython関数を作成でき、それらはプラットフォームで直接実行されます。

コードを使用すると、Webhook を受信するための公開 HTTP エンドポイントを設定せずに外部システムにデータを送信できます。また、イベントの発生に応じてトリガーされるカスタム機能の構築も可能です。さらに、人気の事前構築済みモジュールにアクセスし、カスタムソリューションの作成に活用できます。

トピック

以下の例外を除き、CodeではGet Events APIを介してクエリできるイベントに応じて、カスタム関数を実行できます。

以下のようなブロックが用意されています。

• メールイベント（例：メールをクリック、メールをスパムとしてマーク）
• SMS イベント（例：Sent SMS、Received SMS）
• プッシュ通知イベント（例：プッシュ受信、プッシュのバウンス）
• 外部連携からのイベント（つまり、Klaviyoが作成したファーストパーティ外部連携からのイベント）
• API イベント（つまり、Klaviyo の API を通じて同期されるイベント）

権限の付与

Codeに初めてアクセスすると、Code OAuthアプリケーションの承認を求められます。これにより、Code関数がKlaviyoアカウント内のデータにアクセスできるようになります。

アクセスを許可すると、Codeに戻ります。セットアップ確認が表示された場合は、続行するには閉じるをクリックしてください。

関数を作成

1. データ管理>コードに移動してください。
2. まだ関数を作成していない場合は開始をクリックし、すでに関数がある場合は関数を作成をクリックしてください。

3. レシピページで、事前構築済みのレシピ、空のPython関数、または空のNode.js関数を選択してください。

4. 事前構築済みのレシピを選択する場合は、そのコードと手順を確認し、続行するには選択をクリックしてください。

5. 詳細ステップで、関数を設定します：
   • 関数に名前を付ける
     関数を識別するための名前。
   • トリガーを選択
     コードの実行をトリガーするイベントです。
   • Runtimeを確認する
     Runtimeは、選択した空白の関数またはレシピ（PythonまたはNode.js）によって自動的に設定されます。

6. [関数を作成]をクリックします。関数は次のタブで構成されています：

• エディター
• テスト
• ログ

エディター

Codeの[エディター]ページでは、ページが3つのタブに分かれて表示されます：

• コード
  コードタブには、PythonまたはJavaScriptの関数を記述できるエディターがあります。
• モジュール
  モジュールは、関数に機能を追加するサード パーティ パッケージです。
• 環境変数
  環境変数は、関数が実行時にアクセスするキーと値のペアです。

コード

コードタブでは、選択したトピックに応じて実行されるPythonまたはJavaScript関数を記述できるエディターが表示されます。

ハンドラー関数のパラメーター

空の関数またはレシピで提供されるエントリーポイント構造を維持してください。Pythonでは、handlerという名前の関数を使用してください。JavaScriptでは、デフォルトエクスポートされた関数を使用してください。どちらも2つのパラメーターを受け入れます：

• イベント
  トリガーとなるイベントのデータがJSON:API形式で含まれています。イベント以外のトリガー（例：リストへの追加）が設定されたフロー内のカスタムアクションの場合、このパラメータはPythonではNone、JavaScriptではnullになります。
• コンテキスト
  関数呼び出しに関連付けられたプロファイルを含め、関数実行に関する追加メタデータが含まれます。Javascript では context.profile を、Pythonでは context["profile"] を介してプロファイルオブジェクトにアクセスできます。

以下は、ハンドラー関数に渡されるイベント パラメータとコンテキスト パラメータの例です。

イベント形式の例

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

コンテキスト形式の例

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

モジュール

モジュール タブでは、最も人気のある事前構築済みモジュール（つまり、関数に機能を追加するサードパーティ パッケージ）から選択できます。

1. モジュールタブで、モジュールを追加をクリックしてください。モジュールがすでにインストールされている場合は、新しいモジュールを追加をクリックしてください。

2. モジュールを検索します。バージョンのドロップダウンが利用可能な場合はバージョンを選択し、追加をクリックします。

追加後は、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());
};

環境変数

環境変数タブでは、Klaviyo 内でコードが実行される際に参照できるキーと値のペアを設定できます。これらは、認証情報やシークレットキーなどの情報を保存するために使用でき、関数は実行中にそれらへアクセスできます。

1. 環境変数タブで、変数を追加をクリックします。

2. 変数のキーと値を入力し、保存をクリックしてください。

作成後、環境変数がページに一覧表示され、コード内で使用できます。

テスト

Testタブでは、最近のイベントで関数を実行し、そのログとエラーを確認できます。

関数をテストするには:

1. テストタブを開き、テストを実行をクリックしてください。すでにイベントが選択されている場合は、別のイベントを選択するためにイベントを変更をクリックしてください。

2. テストを実行するイベントを選択してください。過去30日間の機能トリガーとして、最新のイベントから最大10件を選択できます。

3. テスト出力パネルでログとエラーを確認してください。

同じイベントで関数を再度実行するには、エディタ上部のテストをクリックしてください。別のイベントを使用するには、イベントを変更をクリックしてください。

ログ

Logs タブには、進行中のコード関数の健全性が表示されます。次の内容が表示されます：

• ステータス
  実行が完了したか失敗したかを示します。
• 実行時間
  関数の実行にかかった時間（ミリ秒）。
• Date
  関数が実行された日時のタイムスタンプ。

実行IDをクリックしてログを表示します。その実行の詳細情報については、すべての詳細を表示をクリックしてください。

実行制限

Klaviyo Codeには次の実行制限があります：

• 関数のタイムアウト
  Code内の関数は、タイムアウトするまで最大15秒間実行できます。
• 関数レート制限
  Code の Functions では、関数ごとに最大 25 件の同時実行が可能です。

コードを展開中

関数をテストした後、ステータスのドロップダウンからライブを選択してデプロイしてください。

デプロイに失敗した場合は、エディタータブでエラーを確認し、コードを修正してから、再度お試しください。

ライブに設定すると、作成したコードは、Klaviyo でトピックイベントがキャプチャされるたびに実行されます。

解決策の例

以下は、コードを使用して実装されるカスタムソリューションの例です。

この例では、顧客がブランドで撮影を予約すると、Booked shootカスタムイベントがキャプチャされます。この関数はイベントのbooking_cityプロパティとbooking_postcard_urlプロパティを読み取り、それらをまとめて顧客のプロファイルに保存し、ターゲットメールとセグメンテーションに使用します。

最近の予約プロファイルプロパティには、この関数によって処理された予約のリストが保存されます。最近処理した予約を5件保持するために、上限を5に設定してください。これらはメールテンプレート内でループ処理できます。

コード

このソリューションの Python コードはコードエディターで記述され、Klaviyo によって直接実行されます。

コード例

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)

モジュール

この例では、組み込みの klaviyo モジュールが使用されています。klaviyo モジュールは、関数に klaviyo-api モジュールが追加されていることを前提としています。追加すると、klaviyo モジュールが認証を処理するため、API キーは不要です。

環境変数

環境変数を使用すると、認証情報やシークレットキーなどの情報を保存でき、関数が実行中にそれらへアクセスできます。この例では、次のキーと値のペアが設定されています：

• MAX_PROPERTIES_TO_STORE[最近の予約]に最大5件の予約を保持するには、この環境変数の[値]
  を5 に設定してください。[保存] をクリックします。

テスト

イベントデータをプロファイルプロパティとして設定する関数を作成する際、Test タブを使用して、想定される出力を検証します。

ログ

関数をテストしてライブに設定した後、ログタブに、Booked shootイベントによってトリガーされた実行結果が表示されます。

達成できること

この Code 関数を導入すると、顧客が撮影にサインアップしてカスタム Booked shoot イベントをトリガーした際に、イベントデータが顧客プロファイルに保存され、セグメンテーションやターゲット キャンペーンに活用できるようになります。

レシピの実装 

Code のレシピを使用すると、カスタム開発を行わずに事前構築済みのソリューションを実装できます。

Klaviyo アカウントでレシピを実装するには：

1. [コード]ページで、初めて関数を作成する場合は[開始する]をクリックし、すでに関数がある場合は[関数を作成]をクリックします。
2. 使用するレシピを選択してください。プレビューでコードと手順を確認してください。
3. [選択] ボタンをクリックして続行します。
   

4. 関数の名前と、それを実行するトリガーを選択します。ランタイムは、レシピのコードに基づいて自動的に設定されます。
5. [関数を作成] ボタンを選択します。
6. 関数を作成したら、関数の実行に必要なデータが取得できるように、該当する環境変数を設定します。
7. テストタブで機能をテストします。想定どおりの結果であることを確認したら、ステータスのドロップダウンから本番を選択します。

その他のリソース