デベロッパーガイド
Getting Started
Event Structure

イベントストラクチャ

2024年2月12日に最終更新

イベントストラクチャ

Event Category (string, required): イベント名です。全てのイベントにはイベントカテゴリー(イベント名)が必須で存在します。Airbridgeが収集するイベントのうち、イベントカテゴリー(イベント名)がないイベントはありません。
- Event Action (string, optional): イベントの属性1です。
- Event Label (string, optional): イベントの属性2です。
Event Value (float, optional): イベントの値(numeric)です。発生したイベントの価値を集計(aggregation)する時に有効です。
セマンティックアトリビュート(map, optional): Airbridgeであらかじめ定義したイベントのキー値の属性です。イベントカテゴリーによってセマンティックアトリビュートが定められています。詳細は以下のセマンティックアトリビュートのセクションを参照してください。
カスタムアトリビュート(map, optional): 自由に追加して活用できるイベントのキー値の属性です。詳細は以下のカスタムアトリビュートのセクションを参照してください。

Event Category、Action、Labelのバリデーション仕様は FAQのセクションを確認してください。

イベントタクソノミーを設計する時、カテゴリー、アクション、ラベルなどの属性名はあまり気にする必要はありません。
Event Actionには必ずユーザーの行動を意味する値を、Event Labelには必ずラベルのような値を入れる必要はありません。重要なのは、Event Category(イベント名)は必須の属性で、ActionやLabelはActual Reportでより詳細にイベントを区別して見たい時に使う属性ということです。Event Category(イベント名)で全てのイベントを区別したいなら、Action、Labelを使う必要はありません。以下のイベントタクソノミーの例を参照してください。

カスタムアトリビュートの代わりにAction、Labelを使う理由
Event Category、Event Action、Event Labelの値はインテクシングして迅速にAggregationの値を提供できるできるため、活用度が高いです。
Raw Data ExportやS3 Integrationを使って直接JSON Stringフォーマットのカスタムアトリビュートをパーシングし、データ分析に活用するケースのみ存在するなら問題ありませんが、Actual ReportでAggregationの値を確認したい時や、Raw Data Exportで属性別に区分されたカラムを確認したい時はAction、Labelを使うことを推奨します。

イベントタクソノミーの例

Action、Labelを使わない例

Event Category	Event Action	Event Label	Event Value	Sample Code (Web)
purhcase_card	-	-	35	`airbridge.events.send("purchase_card", { "value": 35 })`
purchase_cash	-	-	55	`airbridge.events.send("purchase_cash", { "value": 55 })`

Action, Labelを使わないActual Reportの例

Action、Labelを使う例

Event Category	Event Action	Event Label	Event Value	Sample Code (Web)
add_to_wishlist	Shoe	364757-103	35	`airbridge.events.send("add_to_wishlist", { "action": "Nike", "label": "364757-103", "value": 35000 })`
add_to_wishlist	Cloth	679421-480	189	`airbridge.events.send("add_to_wishlist", { "action": "Adidas", "label": "679421-480", "value": 189000 })`

Action, Labelを使うActual Reportの例

セマンティックアトリビュート

セマンティックアトリビュートはAirbridgeのシステムであらかじめ定められたキー値です。Airbridgeはセマンティックアトリビュートを活用してRaw Data Exportのカラムを提供し、メディアで意図したパラメータの値を入れてポストバックを送信します。Event Category別のセマンティックアトリビュートについてはリンクを参照してください。

キー	タイプ	説明
totalValue	float	総売上高(商品価値の合計)
contributionMargin	float	貢献利益の売上高
currency	string	通貨
totalQuantity	int	全体の数
transactionID	string	取引ID
cartID	string	カートID
productListID	string	商品リストID
inAppPurchased	boolean	アプリ内購入の判定 true: アプリ内購入 false: アプリ内購入に該当しない
query	string	ユーザー検索クエリ
products	array	商品リスト
products.$0.productID	string	商品ID
products.$0.name	string	商品名
products.$0.price	float	商品価格
products.$0.quantity	int	商品数
products.$0.currency	string	通貨の単位
products.$0.position	int	商品の位置

12345678910111213141516171819
// Example code for semanticAttributes                     
airbridge.events.send("purchase_card", {
  semanticAttributes: {
    transactionID: '1458132a-0d09-4944-a686-fcbee81b74f7',
    products: [{
      productID: "1234",
      name: "Nike 1",
      price: 55,
      currency: "USD",
      quantity: 1
    }, {
      productID: "1235",
      name: "Nike 2",
      price: 44,
      currency: "USD",
      quantity: 1
    }]
  }
});

12345678910111213141516171819202122232425
#import <AirBridge/ABInAppEvent.h>

ABInAppEvent* event = [[ABInAppEvent alloc] init];

[event setCategory:@"purchase_card"];

NSDictionary* semantics = @{
    @"transactionID": @"1458132a-0d09-4944-a686-fcbee81b74f7",
    @"products": @[@{
        @"productID": @"1234",
        @"name": @"Nike 1",
        @"price": @55,
        @"currency": @"USD",
        @"quantity": @1,
    }, @{
        @"productID": @"1235",
        @"name": @"Nike 2",
        @"price": @44,
        @"currency": @"USD",
        @"quantity": @1,
    }],
};
[event setSemantics:semantics];

[event send];

1234567891011121314151617181920212223
let event = ABInAppEvent()

event?.setCategory("purchase_card")

let semantics: [String: Any] = [
    "transactionID": "1458132a-0d09-4944-a686-fcbee81b74f7",
    "products": [[
        "productID": "1234",
        "name": "Nike 1",
        "price": 55,
        "currency": "USD",
        "quantity": 1,
    ], [
        "productID": "1235",
        "name": "Nike 2",
        "price": 44,
        "currency": "USD",
        "quantity": 1,
    ]]
]
event?.setSemantics(semantics)

event?.send()

123456789101112131415161718192021222324252627282930
Map<String, Object> product1 = new HashMap<>();
product1.put("productID", "1234");
product1.put("name", "Nike 1");
product1.put("price", 55);
product1.put("currency", "USD");
product1.put("quantity", 1);

Map<String, Object> product2 = new HashMap<>();
product1.put("productID", "1235");
product1.put("name", "Nike 2");
product1.put("price", 44);
product1.put("currency", "USD");
product1.put("quantity", 1);

List<Map<String, Object>> products = new ArrayList<>();
products.add(product1);
products.add(product2);

Map<String, Object> semanticAttributes = new HashMap<>();
semanticAttributes.put("transactionID", "1458132a-0d09-4944-a686-fcbee81b74f7");
semanticAttributes.put("product", products);

Airbridge.trackEvent(
  "purchase_card", // Category
  null, // Action
  null, // Label
  null, // Value
  null, // Custom Attributes
  semanticAttributes // Semantic Attributes
);

123456789101112131415161718192021222324
Airbridge.trackEvent(
  category = "purchase_card",
  semanticAttributes = mapOf(
    "transactionID" to "1458132a-0d09-4944-a686-fcbee81b74f7",
    "products" to mapOf(
      "product" to listOf(
        mapOf(
          "productID" to "1234",
          "name" to "Nike 1",
          "price" to 55,
          "currency" to "USD",
          "quantity" to 1
        ),
        mapOf(
          "productID" to "1235",
          "name" to "Nike 2",
          "price" to 44,
          "currency" to "USD",
          "quantity" to 1
        )
      )
    )
  )
)

semanticAttributes.totalQuantityはSDKやAPIなどでイベント収集の時に追加しなくても、プロダクトリストにquantity(semanticAttributes.products.$.quantity)が存在する場合、それらの値の合計が自動的に入り、Raw Data Exportで提供されます。

<イベント送信の例 >

1234567891011121314151617
airbridge.events.addedToCart({
  products: [
    {
      productID: "1",
      name: "MacBook Pro",
      price: 1500000,
      quantity: 3
    },
    {
      productID: "2",
      name: "MacBook Air",
      price: 1500000,
      quantity: 2
    }
  ],
  cartID: "73926365"
});

<イベント送信結果のセマンティックアトリビュート>

12345678910111213141516171819202122
{
  "totalQuantity": 5,   // Total quantity of items are automatically summed
  "cartID": "73926365",
  "products": [
    {
      "quantity": 3,
      "productID": "1",
      "price": 1500,
      "name": "MacBook Pro",
      "currency": "USD",
      "position": 1
    },
    {
      "quantity": 2,
      "productID": "2",
      "price": 1500,
      "name": "MacBook Air",
      "currency": "USD",
      "position": 2
    }
  ]
}

払い戻し及び交換イベントの場合

払い戻しや交換などのイベントを収集した時、products.$0.priceの値にマイナスの数字を入れて活用できます。
例えば、お客様がKRW 12,000ウォンの靴を購入した後、KRW 10,000ウォンの商品に交換を完了した場合、以下の例のように利用できます。

12345678
airbridge.events.send("exchange", {
    semanticAttributes: {
        products: [{
            "name": "shoe",
            "price": -2000
       }]
    }
})

カスタムアトリビュート

カスタムアトリビュートを活用して、セマンティックアトリビュートで提供されない属性値を自由に定義して利用できます。カスタムアトリビュートを使ってイベントのカスタム属性値をメディアにポストバックすることや、Raw Data Exportで活用することができます。

1234567
//Example code for customAttributes
airbridge.events.send("purchase_card", {
  "customAttributes": {
    "userRank": "1",
    "itemType": "sword"
  }
})

123456789101112
#import <AirBridge/ABInAppEvent.h>

ABInAppEvent* event = [[ABInAppEvent alloc] init];

[event setCategory:@"purchase_card"];
NSDictionary* customs = @{
    @"userRank": @"1",
    @"itemType": @"sword"
};
[event setCustoms:customs];
                      
[event send];

123456789101112
Map<String, Object> customAttributes = new HashMap<>();
customAttributes.put("userRank", "1");
customAttributes.put("itemType", "sword");

Airbridge.trackEvent(
  "purchase_card", // Category
  null, // Action
  null, // Label
  null, // Value
  customAttributes, // Custom Attributes
  null, // Semantic Attributes
);

カスタムアトリビュートの代わりにセマンティックアトリビュートを使うメリット
Raw Data Export(S3ダンプを含む)でイベント属性別のカラムが提供されます。(Search Query、Transaction ID、Product IDなど各属性別にデータが提供され、カスタムアトリビュートを使う場合はJSON Stringで提供されます。)
メディアへのポストバックやサードパーティソリューションイベントを送信する時、イベントの属性が自動でマッピングされます。例えば、ユーザー検索クエリの値を受信するメディアではAirbridgeとポストバックを連携する際にsemanticAttributes.queryをすでに連携してあるため、セマンティックアトリビュートを使えば広告主の方では別途作業を行う必要がありません。

このページは役に立ちましたか？

ご質問やご提案はありますか？

イベントストラクチャself.__wrap_n!=1&&self.__wrap_b(":R96fnkv79uuba:",0.5)

イベントストラクチャ

イベントタクソノミーを設計する時、カテゴリー、アクション、ラベルなどの属性名はあまり気にする必要はありません。

カスタムアトリビュートの代わりにAction、Labelを使う理由

イベントタクソノミーの例

Action、Labelを使わない例

Action、Labelを使う例

セマンティックアトリビュート

払い戻し及び交換イベントの場合

カスタムアトリビュート

カスタムアトリビュートの代わりにセマンティックアトリビュートを使うメリット

イベントストラクチャ