筛选项

追踪 Commerce, Content, Lifecycle 以及自定义事件

📘

V1 Events

Branch will be removing support for our v1 Events API endpoint on September 4, 2023. The v1 Events API endpoint will no longer function after this date and this will impact your app experience. Branch highly recommends you update your app with the latest version to avoid any impact to your app experience.

Please confirm which version you have installed in your app. If your app is utilizing the following methods to track events, please update the version and use our current methods that we guide here.

  • sendCommerceEvent()
  • userCompletedAction()
  • Branch.track()

概述

默认情况下,Branch SDK 会自动(不需额外设置)追踪点击,打开,安装,重新安装和展示。

同样,Branch Web SDK 会自动(不需额外设置)跟踪网页浏览,网页端会话开始,点击和展示。

我们也重新标准化了您追踪事件类别(classes)的方式。例如:与客户购买相关的所有事件都归类在 "Purchase" 类别数据项中,与用户和您的应用内内容进行交互的所有相关事件都与"内容"类数据项相关联。

以下是您可能会感兴趣的追踪事件类型的示例,我们将向您展示追踪我们 SDK 的方式。

Events for Optimization

When Universal Ads is enabled, tracking these events will postback to the attributed Ad Network. For example, if you track the purchase event through Branch, this will automatically map to Facebook's Purchase event if the user is attributed to Facebook.

These events will also have analytics like counts and cohorts, so you can understand their performance even when using SafeTrack Attribution.

可用事件

🚧

Event Tracking Disclaimer

Branch may implement caps/overages on the number of events you are tracking. We recommend that you only track events that are useful for your analytics and attribution needs. Additionally, this will avoid unnecessary network calls that your app will make leading to better app performance.

📘

Facebook Ads Support

If you are sending any event Server to Server to Branch and are running Facebook campaigns on iOS, it is required to send the OS version for Branch to provide attribution on Facebook ads.

商业活动

Event 名称iOSAndroidWeb/API
添加到购物车BranchStandardEventAddToCartBRANCH_STANDARD_EVENT.ADD_TO_CARTADD_TO_CART
加到收藏夹BranchStandardEventAddToWishlistBRANCH_STANDARD_EVENT.ADD_TO_WISHLISTADD_TO_WISHLIST
查看购物车BranchStandardEventViewCartBRANCH_STANDARD_EVENT.VIEW_CARTVIEW_CART
发起购买BranchStandardEventInitiatePurchaseBRANCH_STANDARD_EVENT.INITIATE_PURCHASEINITIATE_PURCHASE
添加付款信息BranchStandardEventAddPaymentInfoBRANCH_STANDARD_EVENT.ADD_PAYMENT_INFOADD_PAYMENT_INFO
点击广告BranchStandardEventClickAdBRANCH_STANDARD_EVENT.CLICK_ADCLICK_AD
购买BranchStandardEventPurchaseBRANCH_STANDARD_EVENT.PURCHASEPURCHASE
保留BranchStandardEventReserveBRANCH_STANDARD_EVENT.RESERVERESERVE
消费积分BranchStandardEventSpendCreditsBRANCH_STANDARD_EVENT.SPEND_CREDITSSPEND_CREDITS
查看广告BranchStandardEventViewAdBRANCH_STANDARD_EVENT.VIEW_ADVIEW_AD

Content Event

Event 名称iOSAndroidWeb/API
搜索BranchStandardEventSearchBRANCH_STANDARD_EVENT.SEARCHSEARCH
查看商品BranchStandardEventViewItemBRANCH_STANDARD_EVENT.VIEW_ITEMVIEW_ITEM
查看商品BranchStandardEventViewItemsBRANCH_STANDARD_EVENT.VIEW_ITEMSVIEW_ITEMS
频率BranchStandardEventRateBRANCH_STANDARD_EVENT.RATERATE
分享BranchStandardEventShareBRANCH_STANDARD_EVENT.SHARESHARE
启动流BranchStandardEventInitiateStreamBRANCH_STANDARD_EVENT.INITIATE_STREAMINITIATE_STREAM
Complete StreamBranchStandardEventCompleteStreamBRANCH_STANDARD_EVENT.COMPLETE_STREAMCOMPLETE_STREAM

Lifecycle Event

Event 名称iOSAndroidWeb/API
完成注册BranchStandardEventCompleteRegistrationBRANCH_STANDARD_EVENT.COMPLETE_REGISTRATIONCOMPLETE_REGISTRATION
完成教程BranchStandardEventCompleteTutorialBRANCH_STANDARD_EVENT.COMPLETE_TUTORIALCOMPLETE_TUTORIAL
达标级别BranchStandardEventAchieveLevelBRANCH_STANDARD_EVENT.ACHIEVE_LEVELACHIEVE_LEVEL
解锁成就BranchStandardEventUnlockAchievementBRANCH_STANDARD_EVENT.UNLOCK_ACHIEVEMENTUNLOCK_ACHIEVEMENT
邀请BranchStandardEventInviteBRANCH_STANDARD_EVENT.INVITEINVITE
登录BranchStandardEventLoginBRANCH_STANDARD_EVENT.LOGINLOGIN
开始试用BranchStandardEventStartTrialBRANCH_STANDARD_EVENT.START_TRIALSTART_TRIAL
SubscribeBranchStandardEventSubscribeBRANCH_STANDARD_EVENT.SUBSCRIBESUBSCRIBE
选择加入Tracked via handleATTAuthorizationStatus()不适用不适用
选择退出Tracked via handleATTAuthorizationStatus()不适用不适用

自订活动

Custom Events can be tracked if the event does not fall within one of the categories above.

Note: Custom data in the Branch dashboard is viewable in Liveview and Exports.

追踪 Commerce Event

Commerce Event 描述客户与您的产品进行交互并通过购买进行转化相关的事件。这些事件包括添加付款信息,购买,查看产品等。如果启用了 Branch Universal Ads(全域广告归因),这些事件将自动映射到部分广告合作伙伴。首先为与您重新追踪的事件相关联的每个产品创建一个 Branch Universal Object。

从那里,将 Branch Universal Object 添加到追踪的事件,并使用正确的预定义常量。例如,下面的代码片段用于追踪用户何时将其添加到购物车,但只需将该常量替换为另一个常量即可追踪不同的事件。

📘

Currency and Exchange Rates

If you track commerce events without a currency, we assume they are USD. If you track commerce events with a currency other than USD, we will convert the revenue specified to USD using a recent exchange rate.

This allows you to easily visualize revenue on the Dashboard across many countries and currencies because all units are USD. The exchange rate is pulled from openexchangerates.org regularly and is generally within an hour of the real-time exchange rate. If you view raw Branch events via either Webhooks or Exports, you can see the exchange rate used.

HTTP API - Commerce Endpoint

POST /v2/event/standard
Content-Type: application/json

参数

Note about required identifiers. You must send up (in user_data):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

Product Category Options

Values available for the product_category field:

Animals & Pet Supplies, Apparel & Accessories, Arts & Entertainment,
Baby & Toddler, Business & Industrial, Cameras & Optics,
Electronics, Food, Beverages & Tobacco, Furniture,
Hardware, Health & Beauty, Home & Garden, Luggage & Bags,
Mature, Media, Office Supplies, Religious & Ceremonial,
Software, Sporting Goods, Toys & Games, Vehicles & Parts

Example - Commerce

// Create a BranchUniversalObject with your content data:
let branchUniversalObject = BranchUniversalObject.init()

// ...add data to the branchUniversalObject as needed...
branchUniversalObject.canonicalIdentifier = "item/12345"
branchUniversalObject.canonicalUrl        = "https://branch.io/item/12345"
branchUniversalObject.title               = "My Item Title"

branchUniversalObject.contentMetadata.contentSchema     = .commerceProduct
branchUniversalObject.contentMetadata.quantity          = 1
branchUniversalObject.contentMetadata.price             = 23.20
branchUniversalObject.contentMetadata.currency          = .USD
branchUniversalObject.contentMetadata.sku               = "1994320302"
branchUniversalObject.contentMetadata.productName       = "my_product_name1"
branchUniversalObject.contentMetadata.productBrand      = "my_prod_Brand1"
branchUniversalObject.contentMetadata.productCategory   = .apparel
branchUniversalObject.contentMetadata.productVariant    = "XL"
branchUniversalObject.contentMetadata.condition         = .new
branchUniversalObject.contentMetadata.customMetadata = [
            "custom_key1": "custom_value1",
            "custom_key2": "custom_value2"
        ]

// Create a BranchEvent:
let event = BranchEvent.standardEvent(.purchase)

// Add the BranchUniversalObject with the content (do not add an empty branchUniversalObject):
event.contentItems     = [ branchUniversalObject ]

// Add relevant event data:
event.alias            = "my custom alias"
event.transactionID    = "12344555"
event.currency         = .USD
event.revenue          = 1.5
event.shipping         = 10.2
event.tax              = 12.3
event.coupon           = "test_coupon"
event.affiliation      = "test_affiliation"
event.eventDescription = "Event_description"
event.searchQuery      = "item 123"
event.customData       = [
    "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
    "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
]
event.logEvent() // Log the event.
// Create a BranchUniversalObject with your content data:
BranchUniversalObject *branchUniversalObject = [BranchUniversalObject new];

// ...add data to the branchUniversalObject as needed...
branchUniversalObject.canonicalIdentifier = @"item/12345";
branchUniversalObject.canonicalUrl        = @"https://branch.io/item/12345";
branchUniversalObject.title               = @"My Item Title";

branchUniversalObject.contentMetadata.contentSchema     = BranchContentSchemaCommerceProduct;
branchUniversalObject.contentMetadata.quantity          = 1;
branchUniversalObject.contentMetadata.price             = [[NSDecimalNumber alloc] initWithDouble:23.20];
branchUniversalObject.contentMetadata.currency         = BNCCurrencyUSD;
branchUniversalObject.contentMetadata.sku               = @"1994320302";
branchUniversalObject.contentMetadata.productName       = @"my_product_name1";
branchUniversalObject.contentMetadata.productBrand      = @"my_prod_Brand1";
branchUniversalObject.contentMetadata.productCategory   = BNCProductCategoryApparel;
branchUniversalObject.contentMetadata.productVariant    = @"XL";
branchUniversalObject.contentMetadata.condition         = @"NEW";
branchUniversalObject.contentMetadata.customMetadata =  (NSMutableDictionary*) @{
    @"content_custom_key1": @"content_custom_value1",
    @"content_custom_key2": @"content_custom_value2"
};

// Create an event and add the BranchUniversalObject to it.
BranchEvent *event     = [BranchEvent standardEvent:BranchStandardEventAddToCart];

// Add the BranchUniversalObjects with the content (do not add an empty branchUniversalObject):
event.contentItems     = (id) @[ branchUniversalObject ];

// Add relevant event data:
event.alias            = @"my custom alias";
event.transactionID    = @"12344555";
event.currency         = BNCCurrencyUSD;
event.revenue          = [NSDecimalNumber decimalNumberWithString:@"1.5"];
event.shipping         = [NSDecimalNumber decimalNumberWithString:@"10.2"];
event.tax              = [NSDecimalNumber decimalNumberWithString:@"12.3"];
event.coupon           = @"test_coupon";
event.affiliation      = @"test_affiliation";
event.eventDescription = @"Event_description";
event.searchQuery      = @"item 123";
event.customData       = (NSMutableDictionary*) @{
    @"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
    @"Custom_Event_Property_Key2": @"Custom_Event_Property_val2"
};
[event logEvent];
BranchUniversalObject buo = new BranchUniversalObject()
    .setCanonicalIdentifier("myprod/1234")
    .setCanonicalUrl("https://test_canonical_url")
    .setTitle("test_title")
    .setContentMetadata(
        new ContentMetadata()
        .addCustomMetadata("custom_metadata_key1", "custom_metadata_val1")
        .addCustomMetadata("custom_metadata_key1", "custom_metadata_val1")
        .addImageCaptions("image_caption_1", "image_caption2", "image_caption3")
        .setAddress("Street_Name", "test city", "test_state", "test_country", "test_postal_code")
        .setRating(5.2, 6.0, 5)
        .setLocation(-151.67, -124.0)
        .setPrice(10.0, CurrencyType.USD)
        .setProductBrand("test_prod_brand")
        .setProductCategory(ProductCategory.APPAREL_AND_ACCESSORIES)
        .setProductName("test_prod_name")
        .setProductCondition(ContentMetadata.CONDITION.EXCELLENT)
        .setProductVariant("test_prod_variant")
        .setQuantity(1.5)
        .setSku("test_sku")
        .setContentSchema(BranchContentSchema.COMMERCE_PRODUCT))
        .addKeyWord("keyword1")
        .addKeyWord("keyword2");

//  Do not add an empty branchUniversalObject to the BranchEvent

new BranchEvent(BRANCH_STANDARD_EVENT.ADD_TO_CART)
        .setAffiliation("test_affiliation")
        .setCustomerEventAlias("my_custom_alias")
        .setCoupon("Coupon Code")
        .setCurrency(CurrencyType.USD)
        .setDescription("Customer added item to cart")
        .setShipping(0.0)
        .setTax(9.75)
        .setRevenue(1.5)
        .setSearchQuery("Test Search query")
        .addCustomDataProperty("Custom_Event_Property_Key1", "Custom_Event_Property_val1")
        .addCustomDataProperty("Custom_Event_Property_Key2", "Custom_Event_Property_val2")
        .addContentItems(buo)
        .logEvent(context);
val buo = BranchUniversalObject()
 .setCanonicalIdentifier("myprod/1234")
 .setCanonicalUrl("https://test_canonical_url")
 .setTitle("test_title")
 .setContentMetadata(
   ContentMetadata()
     .addCustomMetadata("custom_metadata_key1", "custom_metadata_val1")
     .addCustomMetadata("custom_metadata_key1", "custom_metadata_val1")
     .addImageCaptions("image_caption_1", "image_caption2", "image_caption3")
     .setAddress("Street_Name", "test city", "test_state", "test_country", "test_postal_code")
     .setRating(5.2, 6.0, 5)
     .setLocation(-151.67, -124.0)
     .setPrice(10.0, CurrencyType.USD)
     .setProductBrand("test_prod_brand")
     .setProductCategory(ProductCategory.APPAREL_AND_ACCESSORIES)
     .setProductName("test_prod_name")
     .setProductCondition(ContentMetadata.CONDITION.EXCELLENT)
     .setProductVariant("test_prod_variant")
     .setQuantity(1.5)
     .setSku("test_sku")
     .setContentSchema(BranchContentSchema.COMMERCE_PRODUCT)
 )
.addKeyWord("keyword1")
.addKeyWord("keyword2")


//  Do not add an empty branchUniversalObject to the BranchEvent
   BranchEvent(BRANCH_STANDARD_EVENT.ADD_TO_CART)
     .setAffiliation("test_affiliation")
     .setCustomerEventAlias("my_custom_alias")
     .setCoupon("Coupon Code")
     .setCurrency(CurrencyType.USD)
     .setDescription("Customer added item to cart")
     .setShipping(0.0)
     .setTax(9.75)
     .setRevenue(1.5)
     .setSearchQuery("Test Search query")
     .addCustomDataProperty("Custom_Event_Property_Key1", "Custom_Event_Property_val1")
     .addCustomDataProperty("Custom_Event_Property_Key2", "Custom_Event_Property_val2")
     .addContentItems(buo)
     .logEvent(applicationContext)
let buo = await branch.createBranchUniversalObject(
  "item/12345",
  {
    canonicalUrl: "https://branch.io/item/12345",
    title: "My Item Title",
    contentMetadata: {
      quantity: 1,
      price: 23.20,
      sku: "1994320302",
      productName: "my_product_name1",
      productBrand: "my_prod_Brand1",
      customMetadata: {
            custom_key1: "custom_value1",
            custom_key2: "custom_value2"
            }
    }
    }
)

let params = {
  transaction_id: "tras_Id_1232343434",
  currency: "USD",
  revenue: 180.2,
  shipping: 10.5,
  tax: 13.5,
  coupon: "promo-1234",
  affiliation: "high_fi",
  description: "Preferred purchase",
  purchase_loc: "Palo Alto",
  store_pickup: "unavailable",
  customData: {
   "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
   "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
  }
}
let event = new BranchEvent(BranchEvent.Purchase, [buo], params)
event.logEvent()
BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.PURCHASE);
event.transactionID    = "12344555";
event.currency         = BranchCurrencyType.USD;
event.revenue          = 1.5;
event.shipping         = 10.2;
event.tax              = 12.3;
event.coupon           = "test_coupon";
event.affiliation      = "test_affiliation";
event.eventDescription = "Event_description";
event.searchQuery      = "item 123";
event.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1');
event.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');

FlutterBranchSdk.trackContent(buo: [buo], branchEvent: event);
var event_and_custom_data = {
   "transaction_id": "tras_Id_1232343434",
   "currency": "USD",
   "revenue": 180.2,
   "shipping": 10.5,
   "tax": 13.5,
   "coupon": "promo-1234",
   "affiliation": "high_fi",
   "description": "Preferred purchase",
   "purchase_loc": "Palo Alto",
   "store_pickup": "unavailable"
};

var content_items = [
{
   "$content_schema": "COMMERCE_PRODUCT",
   "$og_title": "Nike Shoe",
   "$og_description": "Start loving your steps",
   "$og_image_url": "http://example.com/img1.jpg",
   "$canonical_identifier": "nike/1234",
   "$publicly_indexable": false,
   "$price": 101.2,
   "$locally_indexable": true,
   "$quantity": 1,
   "$sku": "1101123445",
   "$product_name": "Runner",
   "$product_brand": "Nike",
   "$product_category": "SPORTING_GOODS",
   "$product_variant": "XL",
   "$rating_average": 4.2,
   "$rating_count": 5,
   "$rating_max": 2.2,
   "$creation_timestamp": 1499892854966,
   "$exp_date": 1499892854966,
   "$keywords": [ "sneakers", "shoes" ],
   "$address_street": "230 South LaSalle Street",
   "$address_city": "Chicago",
   "$address_region": "IL",
   "$address_country": "US",
   "$address_postal_code": "60604",
   "$latitude": 12.07,
   "$longitude": -97.5,
   "$image_captions": [ "my_img_caption1", "my_img_caption_2" ],
   "$condition": "NEW",
   "$custom_fields": {"foo1":"bar1","foo2":"bar2"}
},
{
   "$og_title": "Nike Woolen Sox",
   "$canonical_identifier": "nike/5324",
   "$og_description": "Fine combed woolen sox for those who love your foot",
   "$publicly_indexable": false,
   "$price": 80.2,
   "$locally_indexable": true,
   "$quantity": 5,
   "$sku": "110112467",
   "$product_name": "Woolen Sox",
   "$product_brand": "Nike",
   "$product_category": "Apparel & Accessories",
   "$product_variant": "Xl",
   "$rating_average": 3.3,
   "$rating_count": 5,
   "$rating_max": 2.8,
   "$creation_timestamp": 1499892854966
}];

var customer_event_alias = "my custom alias";

branch.logEvent(
   "PURCHASE",
   event_and_custom_data,
   content_items,
   customer_event_alias,
   function(err) { console.log(err); }
);
// Create a BranchUniversalObject with your content data:
        let branchUniversalObject = BranchUniversalObject.init()

        // ...add data to the branchUniversalObject as needed...
        branchUniversalObject.canonicalIdentifier = "item/12345"
        branchUniversalObject.canonicalUrl        = "https://branch.io/item/12345"
        branchUniversalObject.title               = "My Item Title"

        branchUniversalObject.contentMetadata.contentSchema     = .commerceProduct
        branchUniversalObject.contentMetadata.quantity          = 1
        branchUniversalObject.contentMetadata.price             = 23.20
        branchUniversalObject.contentMetadata.currency          = .USD
        branchUniversalObject.contentMetadata.sku               = "1994320302"
        branchUniversalObject.contentMetadata.productName       = "my_product_name1"
        branchUniversalObject.contentMetadata.productBrand      = "my_prod_Brand1"
        branchUniversalObject.contentMetadata.productCategory   = .apparel
        branchUniversalObject.contentMetadata.productVariant    = "XL"
        branchUniversalObject.contentMetadata.condition         = .new
        branchUniversalObject.contentMetadata.customMetadata = [
                    "custom_key1": "custom_value1",
                    "custom_key2": "custom_value2"
                ]

        // Create a BranchEvent:
        let event = BranchEvent.standardEvent(.purchase)

        // Add the BranchUniversalObject with the content (do not add an empty branchUniversalObject):
        event.contentItems     = [ branchUniversalObject ]

        // Add relevant event data:
        
        event.transactionID    = "12344555"
        event.currency         = .USD
        event.revenue          = 1.5
        event.shipping         = 10.2
        event.tax              = 12.3
        event.coupon           = "test_coupon"
        event.affiliation      = "test_affiliation"
        event.eventDescription = "Event_description"
        event.searchQuery      = "item 123"
        event.customData       = [
            "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
            "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
        ]
        
        // The log method is on the Branch singleton instead of the event object
        Branch.sharedInstance.logEvent(event) { (error) in
            // log error here
        }
// Create a BranchUniversalObject with your content data:
    BranchUniversalObject *branchUniversalObject = [BranchUniversalObject new];

    // ...add data to the branchUniversalObject as needed...
    branchUniversalObject.canonicalIdentifier = @"item/12345";
    branchUniversalObject.canonicalUrl        = @"https://branch.io/item/12345";
    branchUniversalObject.title               = @"My Item Title";

    branchUniversalObject.contentMetadata.contentSchema     = BranchContentSchemaCommerceProduct;
    
    branchUniversalObject.contentMetadata.quantity          = 1.0;

    branchUniversalObject.contentMetadata.price             = [NSDecimalNumber decimalNumberWithString:@"23.20"];
    
    branchUniversalObject.contentMetadata.currency          = BNCCurrencyUSD;
    branchUniversalObject.contentMetadata.sku               = @"1994320302";
    branchUniversalObject.contentMetadata.productName       = @"my_product_name1";
    branchUniversalObject.contentMetadata.productBrand      = @"my_prod_Brand1";
    branchUniversalObject.contentMetadata.productCategory   = BNCProductCategoryApparel;
    branchUniversalObject.contentMetadata.productVariant    = @"XL";
    branchUniversalObject.contentMetadata.condition         = @"NEW";
    branchUniversalObject.contentMetadata.customMetadata =  (NSMutableDictionary*) @{
        @"content_custom_key1": @"content_custom_value1",
        @"content_custom_key2": @"content_custom_value2"
    };

    // Create an event and add the BranchUniversalObject to it.
    BranchEvent *event     = [BranchEvent standardEvent:BranchStandardEventAddToCart];

    // Add the BranchUniversalObjects with the content (do not add an empty branchUniversalObject):
    event.contentItems     = (id) @[ branchUniversalObject ];

    // Add relevant event data:
    
    event.transactionID    = @"12344555";
    event.currency         = BNCCurrencyUSD;
    event.revenue          = [NSDecimalNumber decimalNumberWithString:@"1.5"];
    event.shipping         = [NSDecimalNumber decimalNumberWithString:@"10.2"];
    event.tax              = [NSDecimalNumber decimalNumberWithString:@"12.3"];
    event.coupon           = @"test_coupon";
    event.affiliation      = @"test_affiliation";
    event.eventDescription = @"Event_description";
    event.searchQuery      = @"item 123";
    event.customData       = (NSMutableDictionary*) @{
        @"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
        @"Custom_Event_Property_Key2": @"Custom_Event_Property_val2"
    };
    
    [[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
        NSLog(@"Test Standard Event: %@", error);
    }];
curl -vvv -d '{
  "name": "PURCHASE",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": "25",
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "custom_data": {
    "purchase_loc": "Palo Alto",
    "store_pickup": "unavailable"
  },
  "event_data": {
    "transaction_id": "trans_Id_1232343434",
    "currency": "USD",
    "revenue": 180.2,
    "shipping": 10.5,
    "tax": 13.5,
    "coupon": "promo-1234",
    "affiliation": "high_fi",
    "description": "Preferred purchase",
    "custom_param_1": "Parameter 1",
    "custom_param_2": "Parameter 2",
    "custom_param_3": "Parameter 3"
  },
  "content_items": [
    {
      "$content_schema": "COMMERCE_PRODUCT",
      "$og_title": "Nike Shoe",
      "$og_description": "Start loving your steps",
      "$og_image_url": "http://example.com/img1.jpg",
      "$canonical_identifier": "nike/1234",
      "$publicly_indexable": false,
      "$price": 101.2,
      "$locally_indexable": true,
      "$quantity": 1,
      "$sku": "1101123445",
      "$product_name": "Runner",
      "$product_brand": "Nike",
      "$product_category": "Sporting Goods",
      "$product_variant": "XL",
      "$rating_average": 4.2,
      "$rating_count": 5,
      "$rating_max": 2.2,
      "$creation_timestamp": 1499892854966,
      "$exp_date": 1499892854966,
      "$keywords": [
        "sneakers",
        "shoes"
      ],
      "$address_street": "230 South LaSalle Street",
      "$address_city": "Chicago",
      "$address_region": "IL",
      "$address_country": "US",
      "$address_postal_code": "60604",
      "$latitude": 12.07,
      "$longitude": -97.5,
      "$image_captions": [
        "my_img_caption1",
        "my_img_caption_2"
      ],
      "$condition": "NEW",
      "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}"
    },
    {
      "$og_title": "Nike Woolen Sox",
      "$canonical_identifier": "nike/5324",
      "$og_description": "Fine combed woolen sox for those who love your foot",
      "$publicly_indexable": false,
      "$price": 80.2,
      "$locally_indexable": true,
      "$quantity": 5,
      "$sku": "110112467",
      "$product_name": "Woolen Sox",
      "$product_brand": "Nike",
      "$product_category": "Apparel & Accessories",
      "$product_variant": "Xl",
      "$rating_average": 3.3,
      "$rating_count": 5,
       "$rating_max": 2.8,
      "$creation_timestamp": 1499892854966
     }
   ],
   "metadata": {},
   "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
 }' https://api2.branch.io/v2/event/standard
BranchEvent branchEvent = new BranchEvent(BranchEventType.PURCHASE);
branchEvent.AddCustomData("Transaction ID", "12344555");
branchEvent.AddCustomData("Currency", BranchCurrencyType.USD.ToString());
branchEvent.AddCustomData("Revenue", "1.5");
branchEvent.AddCustomData("Shipping", "10.2");
branchEvent.AddCustomData("Tax", "12.3");
branchEvent.AddCustomData("Coupon", "test_coupon");
branchEvent.AddCustomData("Affiliation", "test_affiliation");
branchEvent.AddCustomData("Event Description", "event_description");
branchEvent.AddCustomData("Search Query", "item 123");
branchEvent.AddCustomData("Custom_Event_Property_Key1", "Custom_Event_Property_val1");
branchEvent.AddCustomData("Custom_Event_Property_Key2", "Custom_Event_Property_val2");
Branch.sendEvent(branchEvent);

See full API docs here.

追踪 Content Event

Content Event 是用户与您的应用内内容互动时发生的事件。例如,如果您有应用内文章,则希望追踪与用户搜索,查看内容,对内容进行评级和分享有关的事件。这可以应用于多种应用内内容,例如博客文章,音乐,视频,图片和电子商务目录项。

HTTP API - Content Endpoint

POST /v2/event/standard
Content-Type: application/json

参数

Note about required identifiers. You must send up (in user_data):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

Example - Content

let event = BranchEvent.standardEvent(.search)
event.alias = "my custom alias"
event.eventDescription = "Product Search"
event.searchQuery = "user search query terms for product xyz"
event.customData["Custom_Event_Property_Key1"] = "Custom_Event_Property_val1"
event.logEvent()
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventSearch];
event.alias = @"my custom alias";
event.eventDescription = @"Product Search";
event.searchQuery = @"user search query terms for product xyz";
event.customData = (NSMutableDictionary*) @{
    @"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
    @"Custom_Event_Property_Key2": @"Custom_Event_Property_val2"
};
new BranchEvent(BRANCH_STANDARD_EVENT.SEARCH)
  .setCustomerEventAlias("my_custom_alias")
  .setDescription("Product Search")
  .setSearchQuery("product name")
  .addCustomDataProperty("Custom_Event_Property_Key1", "Custom_Event_Property_val1")
  .logEvent(context);
BranchEvent(BRANCH_STANDARD_EVENT.SEARCH)
 .setCustomerEventAlias("my_custom_alias")
 .setDescription("Product Search")
 .setSearchQuery("product name")
 .addCustomDataProperty("Custom_Event_Property_Key1", "Custom_Event_Property_val1")
 .logEvent(applicationContext);
let params = {
  alias: "my custom alias",
  description: "Product Search",
    searchQuery: "user search query terms for product xyz",
  customData: {
   "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
   "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
  }
}
let event = new BranchEvent(BranchEvent.Search, null, params)
event.logEvent()
BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.SEARCH);
event.eventDescription = "Product Search";
event.searchQuery = "user search query terms for product xyz";
event.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1');
event.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');
FlutterBranchSdk.trackContentWithoutBuo(branchEvent: event);
var event_and_custom_data = {
   "transaction_id": "tras_Id_1232343434",
   "currency": "USD",
   "revenue": 180.2,
   "shipping": 10.5,
   "tax": 13.5,
   "coupon": "promo-1234",
   "affiliation": "high_fi",
   "description": "Preferred purchase",
   "purchase_loc": "Palo Alto",
   "store_pickup": "unavailable"
};

var content_items = [
{
   "$content_schema": "COMMERCE_PRODUCT",
   "$og_title": "Nike Shoe",
   "$og_description": "Start loving your steps",
   "$og_image_url": "http://example.com/img1.jpg",
   "$canonical_identifier": "nike/1234",
   "$publicly_indexable": false,
   "$price": 101.2,
   "$locally_indexable": true,
   "$quantity": 1,
   "$sku": "1101123445",
   "$product_name": "Runner",
   "$product_brand": "Nike",
   "$product_category": "Sporting Goods",
   "$product_variant": "XL",
   "$rating_average": 4.2,
   "$rating_count": 5,
   "$rating_max": 2.2,
   "$creation_timestamp": 1499892854966,
   "$exp_date": 1499892854966,
   "$keywords": [ "sneakers", "shoes" ],
   "$address_street": "230 South LaSalle Street",
   "$address_city": "Chicago",
   "$address_region": "IL",
   "$address_country": "US",
   "$address_postal_code": "60604",
   "$latitude": 12.07,
   "$longitude": -97.5,
   "$image_captions": [ "my_img_caption1", "my_img_caption_2" ],
   "$condition": "NEW",
   "$custom_fields": {"foo1":"bar1","foo2":"bar2"}
},
{
   "$og_title": "Nike Woolen Sox",
   "$canonical_identifier": "nike/5324",
   "$og_description": "Fine combed woolen sox for those who love your foot",
   "$publicly_indexable": false,
   "$price": 80.2,
   "$locally_indexable": true,
   "$quantity": 5,
   "$sku": "110112467",
   "$product_name": "Woolen Sox",
   "$product_brand": "Nike",
   "$product_category": "Apparel & Accessories",
   "$product_variant": "Xl",
   "$rating_average": 3.3,
   "$rating_count": 5,
   "$rating_max": 2.8,
   "$creation_timestamp": 1499892854966
}];

var customer_event_alias = "my custom alias";

branch.logEvent(
   "VIEW_ITEMS",
   event_and_custom_data,
   content_items,
   customer_event_alias,
   function(err) { console.log(err); }
);
// Create a BranchEvent:
let event = BranchEvent.standardEvent(.search)
event.alias = "my custom alias"
event.eventDescription = "Product Search"
event.searchQuery = "user search query terms for product xyz"
event.customData["Custom_Event_Property_Key1"] = "Custom_Event_Property_val1"
// The log method is on the Branch singleton instead of the event object
Branch.sharedInstance.logEvent(event) { (error) in
// log error here
}
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventSearch];
event.alias = "my custom alias";
event.eventDescription = @"Product Search";
event.searchQuery = @"user search query terms for product xyz";
event.customData[@"Custom_Event_Property_Key1"] = @"Custom_Event_Property_val1";
[[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
    NSLog(@"Test Standard Event: %@", error);
}];
curl -vvv -d '{
  "name": "VIEW_ITEMS",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": "25",
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "custom_data": {
    "purchase_loc": "Palo Alto",
    "store_pickup": "unavailable"
  },
  "event_data": {
    "search_query": "red sneakers",
    "description": "Preferred purchase",
    "custom_param_1": "Parameter 1",
    "custom_param_2": "Parameter 2",
    "custom_param_3": "Parameter 3"
  },
  "content_items": [
    {
      "$content_schema": "COMMERCE_PRODUCT",
      "$og_title": "Nike Shoe",
      "$og_description": "Start loving your steps",
      "$og_image_url": "http://example.com/img1.jpg",
      "$canonical_identifier": "nike/1234",
      "$publicly_indexable": false,
      "$price": 101.2,
      "$locally_indexable": true,
      "$sku": "1101123445",
      "$product_name": "Runner",
      "$product_brand": "Nike",
      "$product_category": "Sporting Goods",
      "$product_variant": "XL",
      "$rating_average": 4.2,
      "$rating_count": 5,
      "$rating_max": 2.2,
      "$creation_timestamp": 1499892854966,
      "$exp_date": 1499892854966,
      "$keywords": [
        "sneakers",
        "shoes"
      ],
      "$address_street": "230 South LaSalle Street",
      "$address_city": "Chicago",
      "$address_region": "IL",
      "$address_country": "US",
      "$address_postal_code": "60604",
      "$latitude": 12.07,
      "$longitude": -97.5,
      "$image_captions": [
        "my_img_caption1",
        "my_img_caption_2"
      ],
      "$condition": "NEW",
      "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}"
    },
    {
      "$og_title": "Nike Woolen Sox",
      "$canonical_identifier": "nike/5324",
      "$og_description": "Fine combed woolen sox for those who love your foot",
      "$publicly_indexable": false,
      "$price": 80.2,
      "$locally_indexable": true,
      "$sku": "110112467",
      "$product_name": "Woolen Sox",
      "$product_brand": "Nike",
      "$product_category": "Apparel & Accessories",
      "$product_variant": "Xl",
      "$rating_average": 3.3,
      "$rating_count": 5,
      "$rating_max": 2.8,
      "$creation_timestamp": 1499892854966
    }
  ],
  "metadata": {},
  "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/standard
BranchEvent branchEvent = new BranchEvent(BranchEventType.SEARCH);
branchEvent.SetAlias("my_custom_alias");
branchEvent.AddCustomData("Description", "Product Search");
branchEvent.AddCustomData("Search Query", "product name");
branchEvent.AddCustomData("Custom_Event_Property_Key1", "Custom_Event_Property_val1");
Branch.sendEvent(branchEvent);

See full API docs here.

追踪 Lifecycle Event

Lifecycle Event 事件可以描述为继续操作,用户在应用内产生的事件。当用户完成用户个人资料,注册或完成教程时,这些事件可以应用于游戏应用以及非游戏应用。

HTTP API - Lifecycle Endpoint

POST /v2/event/standard
Content-Type: application/json

参数

Note about required identifiers. You must send up (in user_data):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

Example - Lifecycle

let event = BranchEvent.standardEvent(.completeRegistration)
event.alias = "my custom alias"
event.transactionID = "tx1234"
event.eventDescription = "User completed registration."
event.customData["registrationID"] = "12345"
event.logEvent()
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventCompleteRegistration];
event.alias = "my custom alias";
event.transactionID = @"tx1234";
event.eventDescription = @"User completed registration.";
event.customData = (NSMutableDictionary*) @{
    @"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
    @"Custom_Event_Property_Key2": @"Custom_Event_Property_val2",
    @"registrationID": @"12345"
};
[event logEvent];
new BranchEvent(BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION)
    .setCustomerEventAlias("my_custom_alias")
    .setTransactionID("tx1234")
    .setDescription("User created an account")
    .addCustomDataProperty("registrationID", "12345")
    .logEvent(context);
BranchEvent(BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION)
 .setCustomerEventAlias("my_custom_alias")
 .setTransactionID("tx1234")
 .setDescription("User created an account")
 .addCustomDataProperty("registrationID", "12345")
 .logEvent(applicationContext);
let params = {
  alias: "my custom alias",
  transaction_id: "tras_Id_1234",
  description: "Preferred purchase",
  registration_id: "12345",
  customData: {
   "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
   "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
  }
}
let event = new BranchEvent(BranchEvent.CompleteRegistration, null, params)
event.logEvent()
BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.COMPLETE_REGISTRATION);
event.transactionID = "tx1234";
event.eventDescription = "User completed registration";
event.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1');
event.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');
FlutterBranchSdk.trackContentWithoutBuo(branchEvent: event);
var event_and_custom_data = {
   "transaction_id": "tras_Id_1234",
   "description": "Preferred purchase",
   "registration_id": "12345"
};

var customer_event_alias = "my custom alias";

branch.logEvent(
   "COMPLETE_REGISTRATION",
   event_and_custom_data,
   customer_event_alias,
   function(err) { console.log(err); }
);
// Create a BranchEvent:
let event = BranchEvent.standardEvent(.completeRegistration)
event.alias = "my custom alias"
event.transactionID = "tx1234"
event.eventDescription = "User completed registration."
event.customData["registrationID"] = "12345"
// The log method is on the Branch singleton instead of the event object
Branch.sharedInstance.logEvent(event) { (error) in
// log error here
}
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventCompleteRegistration];
event.alias = "my custom alias";
event.transactionID = @"tx1234";
event.eventDescription = @"User completed registration.";
[[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
    NSLog(@"Test Standard Event: %@", error);
}];
curl -vvv -d '{
  "name": "COMPLETE_REGISTRATION",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": "25",
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "custom_data": {
    "foo": "bar"
  },
  "event_data": {
    "description": "Preferred purchase",
    "custom_param_1": "Parameter 1",
    "custom_param_2": "Parameter 2",
    "custom_param_3": "Parameter 3"
  },
  "metadata": {},
  "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/standard
BranchEvent branchEvent = new BranchEvent(BranchEventType.COMPLETE_REGISTRATION);
branchEvent.SetAlias("my_custom_alias");
branchEvent.AddCustomData("Transaction_ID", "tx1234");
branchEvent.AddCustomData("Description", "User created an account");
branchEvent.AddCustomData("registrationID", "12345");
Branch.sendEvent(branchEvent);

See full API docs here.

追踪自定义事件

如果要追踪非预定义的事件,只需进行以下操作:

📘

自定义事件名称

The name custom event is reserved by Branch. Please ensure you give your custom event an actual name.

Additionally, do not use the same name for your custom event as Standard Events. This will have an impact on attribution with Self-Attributing Networks and event mapping.

We strongly recommend using custom event names that contain no more than 40 characters, contain only letters, numbers, hyphens, spaces, and underscores, and do not start with a hyphen. Facebook will not accept events that violate these rules, and if you enable the Facebook integration, Branch may sanitize your event names to pass validation.

HTTP API - Custom Endpoint

POST /v2/event/custom
Content-Type: application/json

参数

Note about required identifiers. You must send up (in user_data):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

Example - Custom

let event = BranchEvent.customEvent(withName:"User_Scanned_Item")
    event.customData["Custom_Event_Property_Key1"] = "Custom_Event_Property_val1"
    event.customData["Custom_Event_Property_Key2"] = "Custom_Event_Property_val2"
  event.alias = "my custom alias"
    event.logEvent()
BranchEvent *event = [BranchEvent customEventWithName:@"User_Scanned_Item"];
event.customData = (NSMutableDictionary*) @{
    @"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
    @"Custom_Event_Property_Key2": @"Custom_Event_Property_val2"
};
event.alias = "my custom alias";
[event logEvent];
new BranchEvent("Some Custom Event")
    .addCustomDataProperty("Custom_Event_Property_Key11", "Custom_Event_Property_val11")
    .addCustomDataProperty("Custom_Event_Property_Key22", "Custom_Event_Property_val22")
    .setCustomerEventAlias("my_custom_alias")
    .logEvent(MainActivity.this);
BranchEvent("Some Custom Event")
 .addCustomDataProperty("Custom_Event_Property_Key11", "Custom_Event_Property_val11")
 .addCustomDataProperty("Custom_Event_Property_Key22", "Custom_Event_Property_val22")
 .setCustomerEventAlias("my_custom_alias")
 .logEvent(this);
let params = {
  alias: "my custom alias",
  customData: {
   "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
   "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
  }
}
let event = new BranchEvent("Some Custom Event", null, params) //pass null if no BranchUniversalObject is used
event.logEvent()
BranchEvent eventCustom = BranchEvent.customEvent('User_Scanned_Item');
eventCustom.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1')
eventCustom.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');
FlutterBranchSdk.trackContentWithoutBuo(branchEvent: eventCustom);
var custom_data = {
   "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
   "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
};

branch.logEvent(
    'custom_event_name',
    custom_data,
    function(err) { console.log(err); }
);
// Create a BranchEvent:
let event = BranchEvent.customEvent(withName:"User_Scanned_Item")
event.customData["Custom_Event_Property_Key1"] = "Custom_Event_Property_val1"
event.customData["Custom_Event_Property_Key2"] = "Custom_Event_Property_val2"
event.alias = "my custom alias"
// The log method is on the Branch singleton instead of the event object
Branch.sharedInstance.logEvent(event) { (error) in
// log error here
}
BranchEvent *event = [BranchEvent customEventWithName:@"User_Scanned_Item"];
event.customData[@"Custom_Event_Property_Key1"] = @"Custom_Event_Property_val1";
event.customData[@"Custom_Event_Property_Key2"] = @"Custom_Event_Property_val2";
event.alias = "my custom alias";
[[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
    NSLog(@"Test Standard Event: %@", error);
}];
curl -vvv -d '{
  "name": "picture swiped",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": "25",
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "event_data": {
    "custom_param_1": "Parameter 1",
    "custom_param_2": "Parameter 2",
    "custom_param_3": "Parameter 3"
  },
  "custom_data": {
    "foo": "bar"
  },
  "metadata": {},
  "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/custom
BranchEvent branchEvent = new BranchEvent("Some Custom Event");
branchEvent.AddCustomData("Custom_Event_Property_Key11", "Custom_Event_Property_val11");
branchEvent.AddCustomData("Custom_Event_Property_Key22", "Custom_Event_Property_val22");
branchEvent.SetAlias("my_custom_alias");
Branch.sendEvent(branchEvent);

See full API docs here.

测试事件

In order to test whether v2/events are being received on Branch's backend, check out Liveview.