コードのスタートガイド

このページで学べること

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

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

始める前に

コードとは？

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

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

トピック

コードを使用すると、イベント取得 API を通じてクエリ可能な任意のイベントに応答して、カスタム関数を実行できます。

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

• メールイベント（例：Clicked email、Marked email as spam）
• SMS イベント（例：Sent SMS、Received SMS）
• プッシュ通知イベント（例：プッシュ受信、プッシュのバウンス）
• 外部連携からのイベント（例：Klaviyo によって作成されたファーストパーティ外部連携からのイベント）
• API イベント（つまり、Klaviyo の API を通じて同期されるイベント）

コード インターフェース

コードにアクセスするには、[アドバンストKDP] > [データ管理] > [コード]と進み、[コード]タブに移動します。

カスタム関数を作成するには、[関数を作成] ボタンを選択します：

Recipes ページに移動します。ここで、実行するための事前構築済みソリューションを選択するか、空の Python または Node.js 関数を選択できます。

既存のレシピを選択すると、ソリューションのコードが含まれるコードエディターと、機能の説明が表示されます。

独自のカスタムソリューションを作成できるように空白の関数を選択すると、詳細モーダルが表示され、次の操作を行えます：

• 関数に名前を付ける
  関数を識別するための名前。
• 機能のトピックを選択
  コードの実行をトリガーするイベント。
• ランタイムを選択
  コードが実行されるランタイム環境（つまり、Python または Node.js）。

必要な選択を行い、関数を作成ボタンを選択すると、次のタブがあるインターフェースに移動します。

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

権限の付与

Code を通じて初めて関数を作成する際は、Code OAuth アプリケーションの認証を求められます。これは、Code 関数が Klaviyo アカウント内のデータにアクセスできるようにするために必要です。

アクセスを許可すると、コード エディターが表示されます。

エディター

コードの [エディター] ページでは、ページが 3 つのタブに分かれているのが確認できます。

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

コード

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

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

Klaviyo が作成したコードを実行できるようにするには、2 つのパラメータを受け取る「handler」という名前の関数でラップする必要があります。

• イベント
  トリガーとなるイベントに関連付けられたイベントデータ（JSON:API 形式）で構成されます。トリガーがイベントベースでない場合（例：リストに追加）、このパラメータの値は、言語に応じて None または 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",
}

モジュール

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

コードで使用する外部モジュールを追加するには、[モジュールを追加] ボタンを選択します：

表示されるモーダルで、追加するモジュールを検索して選択できます：

追加後は、Klaviyo で作成したコードを使用してモジュールを利用できます。

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

import klaviyodef 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. 表示されるモーダルで、テストに使用するイベントを選択します。Klaviyo で取得された直近 10 件のイベントから選択できます。
   

3. テストするイベントを選択すると、テスト出力が表示されます。

ログ

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

• ステータス
  関数の実行の進行状況。
• 応答時間
  イベントに応じてコードが実行されるまでにかかる時間です。
• Date
  関数が実行された日時のタイムスタンプ。

レート制限

Klaviyo コードには次のレート制限があります。

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

コードを展開中

エディターで作成したコードをデプロイするには、ステータスのドロップダウンを Live に切り替えます。

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

解決策の例

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

この例では、イベント データがプロファイルプロパティとして設定されているため、ターゲットメールやセグメンテーションで使用できます。撮影予約 カスタムイベントは、お客様がブランドで撮影を予約したときに Klaviyo で取得され、予約都市と関連 URL に関するデータが、それぞれのプロファイル上でプロファイルプロパティとして設定されます。

Recent bookings というプロパティも作成され、直近 5 件の Booked shoot イベントのデータを保存します。これにより、メール テンプレート内でループ処理してアクセスできます。

コード

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

コード例

モジュール

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

環境変数

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

• MAX_PROPERTIES_TO_STORE
  サンプル関数で保存するプロパティの最大数を定義するために使用される環境変数です。

テスト

イベントデータをプロファイルプロパティとして設定する関数を作成する際、Test output タブを使用して期待どおりの出力を検証します。

ログ

関数を作成してテストしたら、Logs タブに、Booked shoot イベントに応じて実行される関数の健全性ステータスが表示されます。

達成できること

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

レシピの実装 

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

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

1. コードページで、[関数を作成] ボタンを選択します。
2. アカウントに実装するレシピを選択します。エディターに移動し、選択したレシピのコードと、関数の動作の説明を確認できます。
3. [選択] ボタンをクリックして続行します。
   

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

その他のリソース