Data Science ツールキット - Bonsai スマートリーフ
注:
このページでは、 既に Bonsai 言語 と Bonsai 機能に精通していることを前提としています。
Bonsai 言語を使用して、カスタム予測モデルのデシジョン ツリー ロジックを記述します。 各分岐は、入札を表す単純な数値に評価されるノード ("リーフ") につながります。 スマート リーフは、1 つの静的な値を評価する代わりに、指定された広告のパフォーマンスまたは配信メトリックに基づいて動的に変更された入札値を評価します。 スマートリーフを使用すると、個々のリーフに任意の文字列値を付けることもできます。 これは、デバッグとパフォーマンス分析を支援するために 、標準フィード で使用できます。
注:
スマートリーフは、人間が判読できるデータシリアル化形式である YAML のような形式を使用して定義されます。
compute() 構文
スマートリーフを使用すると、広告メトリックから計算された静的な値または入札を指定したり、入札をまったく行なっていないか指定することができます。 値が計算される場合は、次の形式を compute 使用する式によって決定されます。
value: compute(input_field, multiplier, offset, min_value, max_value)
これは、次の式として評価されます。
max(min_value, min(max_value, input_field * multiplier + offset))
つまり、計算された値は、入力フィールドが乗数の倍にオフセットを加えた値です。 結果が最小値より小さい場合は、最小値が代わりに返されます。 結果が最大値より大きい場合は、最大値が返されます。 計算 (乗数、オフセット、最小値、または最大値) を省略するには、省略された値にアンダースコア (_) を使用します。 乗数の値を指定するために省略した場合、既定値は 1 です。
注:
モデルによって計算される入札は、キャンペーンに別の通貨を指定した場合でも、常に広告主に設定された通貨で表されます。
スマート リーフ フィールド
| フィールド | フィールドの種類 | 説明 | 既定値 |
|---|---|---|---|
value |
テキスト | 入札価格。 ツリー モデルが入札価格の場合、入札はこの広告主の通貨セットで表されます。 ツリー モデルが入札修飾子の場合、入札は浮動小数点数または整数です。 使用可能な値は次のとおりです。 - compute(input_field, multiplier, offset, min_value, max_value)- no_bid- 静的な値 (数値) を指定すると compute 、以下のいずれかの compute() の入力フィールド に基づいて値が計算されます。 計算 (乗数、オフセット、最小値、または最大値) を省略するには、省略された値にアンダースコア (_) を使用します。 警告： 負の数値またはゼロ (0) に評価される式は使用 compute() しないでください。 これらの値はサポートされていないため、予期しない結果が得られます。 明示的に指定 no_bid することをお勧めします。 |
|
leaf_name |
string(7) | デバッグとパフォーマンス分析に役立つログとレポートに渡される省略可能な文字列値。 leaf_name は最大 7 文字の ASCII (7 ビット) 文字であり、一意である必要はありません。メモ： は文字列であるため leaf_name 、値は二重引用符 (") で囲む必要があります。 |
compute() の入力フィールド
入力フィールドの値は、Xandr 最適化によって決定されます。 詳細については、ドキュメントの 拡張行項目の最適化ガイド を参照してください (ログインが必要です)。
| フィールド | 種類 | 説明 |
|---|---|---|
estimated_iab_viewthrough_rate |
float、integer | この Web 表示インプレッションが、IAB 標準01でから から に表示可能として測定される可能性。 |
predicted_iab_video_view_rate |
float、integer | このビデオインプレッションが IAB 標準で表示可能として測定される可能性は、 から 0 まで 1です。 |
predicted_video_completion_rate |
float、integer | ユーザーがこのビデオの印象を完全にwatchする可能性は、 から 0 まで1です。 非ビデオ インベントリは です 0。 |
estimated_average_price |
float、integer | このインプレッションの中央値。 |
estimated_clearing_price |
float、integer | このインプレッションの 80 パーセンタイル価格。 |
uniform |
float、integer | と 1 (0含まれ、1除外) の間0の一様乱数。 |
compute() の入力としてセグメントを使用する
第三者または第三者セグメントのユーザーの値または年齢を使用して計算を実行して、入札値を決定できます。 ユーザーがセグメントに存在しない場合、入札は行われません。 セグメント ID を取得するには、 セグメント サービス を使用します。
| フィールド | 種類 | 説明 |
|---|---|---|
segment[ID].value |
float、integer | ファースト パーティまたはサード パーティのセグメント内のユーザーの値。 ユーザーがセグメントに存在しない場合、入札は行われません。ID はセグメント ID です。 |
segment[ID].age |
float、integer | ファースト パーティまたはサード パーティのセグメント内のユーザーの年齢。 ユーザーがセグメントに存在しない場合、入札は行われません。ID はセグメント ID です。 |
compute() の入力として周波数または再シーを使用する
頻度または再通貨を使用して計算を実行して、入札値を決定できます。
| フィールド | 種類 | 説明 |
|---|---|---|
OBJECT[ID].day_frequency |
float、integer | 現在の日にユーザーが見た広告の数。 これは、広告主、広告申込情報、またはキャンペーンに対して決定できます。 頻度データが見つからない場合、頻度はゼロ (0) としてマークされます。OBJECT は advertiser、 line_item、、または campaignであり、 ID オブジェクト ID です。 広告主サービス、広告申込情報サービス、またはキャンペーン サービスを使用して ID を取得します。 |
OBJECT[ID].lifetime_frequency |
float、integer | 広告主、広告申込情報、キャンペーン、クリエイティブの有効期間中にユーザーが見た広告の数。 頻度データが見つからない場合、頻度はゼロ (0) としてマークされます。OBJECT は advertiser、 line_item、、または campaignであり、 ID オブジェクト ID です。 広告主サービス、広告申込情報サービス、またはキャンペーン サービスを使用して ID を取得します。 |
OBJECT[ID].recency |
float、integer | ユーザーが広告を表示してからの時間 (分)。 これは、広告主、広告申込情報、キャンペーンのすべての広告、または個々のクリエイティブに対して決定できます。 レジェンシー データが見つからない場合、入札は行われません。OBJECT は advertiser、 line_item、、、、 campaignまたは creativeであり、 ID オブジェクト ID です。 広告主サービス、広告申込情報サービス、またはキャンペーン サービスを使用して ID を取得します。 |
例
推定平均価格の入札価格
1 つのリーフには最小許容入札価格がありますが、上限に制限はありません。
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
# This tree determines a bid price as follows:
# 1. If the user is in California, bid the estimated average price * 1.05, plus $0.03.
# 2. Otherwise, bid the estimated average price * .75, but don't bid less than $1.00. There is no maximum bound for bids.
if region = "US:CA":
leaf_name: "eap001"
value: compute(estimated_average_price, 1.05, 0.03, _, _)
else:
leaf_name: "eap002"
value: compute(estimated_average_price, 0.75, 0.00, 1.00, _)
推定クリアリング価格、入札なし、静的価値スマートリーフを含む入札価格ツリー
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
# This tree determines a bid price as follows:
# 1. If the user is in California, bid the estimated clearing price * 1.05, plus $0.03.
# 2. If the user is in New York, bid the estimated clearing price * .75, but don't bid less than $0.10 or more than $1.00.
# 3. If the user is in Delaware, do not bid.
# 4. Otherwise, bid $0.50.
if region = "US:CA":
leaf_name: "ecp_ca"
value: compute(estimated_clearing_price, 1.05, 0.03, _, _)
elif region = "US:NY":
leaf_name: "ecp_ny"
value: compute(estimated_clearing_price, 0.75, _, 0.10, 1.00)
elif region = "US:DE":
leaf_name: "no_de"
value: no_bid
else:
leaf_name: "default"
value: 0.50
推定 IAB ビュースルー率スマート リーフを含む入札価格ツリー
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
# This tree determines a bid modifier as follows:
# 1. If the user is in California, bid the value determined by Xandr optimization multipled by the estimated IAB viewthrough rate and 0.50, plus $0.03.
# 2. If the user is in New York, bid the value determined by Xandr optimization multiplied by the estimated IAB viewthrough rate and 0.75.
# 3. If the user is in Delaware, bid the estimated clearing price, but don't bid less than $0.10 or more than $1.00.
# 4. Otherwise, bid $0.50.
if every region = "US:CA":
leaf_name: "t00001"
value: compute(estimated_iab_viewthrough_rate, 0.50, 0.03, _, _)
elif region = "US:NY":
leaf_name: "t00002"
value: compute(estimated_iab_viewthrough_rate, 0.70, 0.00, _, _)
elif region = "US:DE":
leaf_name: "t00003"
value: compute(estimated_clearing_price, 1.00, _, 0.10, 1.00)
else:
leaf_name: "default"
value: 0.50
セグメント値に基づく入札
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
#1. If the user is in California, bid the value of segment 111 times 2.0, plus 1.0.
#2. Otherwise, do not bid.
if region = "US:CA":
leaf_name: "a00001"
value: compute(segment[111].value, 2.0, 1.0, _, _)
else:
value: no_bid
セグメント年齢に基づく入札
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
#1. If the user is in California, bid the segment age times -.2, plus 8.0, as long as the bid is under 8.0.
#2. Otherwise, do not bid.
if region = "US:CA":
leaf_name: "b00001"
value: compute(segment[111].age, -0.2, 8.0, 0.0, 8.0)
else:
value: no_bid
1 日の頻度に基づく入札
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
#1. If the user is in California and in segment 111, bid the user's daily frequency for line item 222 times -.2, plus 5, with an upper bound of 4.
#2. Otherwise, do not bid.
if every region="US:CA", segment[111]:
leaf_name: "d0001"
value: compute(line_item[222].day_frequency, -0.2, 5.0, 0.0, 4.0)
else:
leaf_name: "d0000"
value: no_bid
有効期間の頻度に基づく入札
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
#1. If the user is in California and in segment 111, bid the lifetime frequency for creative 333 times -.2, plus 8, with an upper bound of 6.
#2. Otherwise, do not bid.
if every region="US:CA", segment[111]:
leaf_name: "e0001"
value: compute(creative[333].lifetime_frequency, -0.2, 8.0, 0.0, 6.0)
else:
leaf_name: "e0000"
value: no_bid
リジェンシーに基づく入札
注:
次のコード例では、 で始まる行は、このツリーのロジックを理解するのに役立つコメントです。
#1. If the user is in California, bid the recency for creative 333 times -.2, plus 8, with an upper bound of 6.
#2. Otherwise, do not bid.
if region="US:CA":
leaf_name: "f0001"
value: compute(creative[333].recency, -0.2, 8.0, 0.0, 6.0)
else:
leaf_name: "f0000"
value: no_bid