├── ISSUE_TEMPLATE └── README.md /ISSUE_TEMPLATE: -------------------------------------------------------------------------------- 1 | If there is a bug or error in this repo, please file the issue here. 2 | 3 | If you need assistance integrating a Branch SDK, please email support@branch.io. Thank you. 4 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Branch-Public-API 2 | 3 | A public API to tie into for fancy integrations. All endpoints are appended to **https://api2.branch.io** 4 | ___ 5 | 6 | ## API Reference 7 | 8 | 1. URL Management 9 | + [Create a single link](#creating-a-deep-linking-url) 10 | + [Bulk create links](#bulk-creating-deep-linking-urls) 11 | + [Update an existing link](#modifying-existing-deep-linking-urls) 12 | + [Retrieve data from existing links](#viewing-state-of-existing-deep-linking-urls) 13 | + [Synchronous, query param link creation with app.link domains](#structuring-a-dynamic-deep-link-for-applink-domains) 14 | + [Synchronous, query param link creation with bnc.lt and custom domains](#structuring-a-dynamic-deep-link-for-bnclt-and-custom-domains) 15 | 16 | 2. Logging Events 17 | + [Logging a commerce event (purchase, add to cart, etc)](#logging-commerce-events) 18 | + [Logging a content event (search, view content items, etc)](#logging-content-events) 19 | + [Logging a user lifecycle event (complete registration, unlock achievement, etc)](#logging-user-lifecycle-events) 20 | + [Logging other custom events](#logging-custom-events) 21 | 22 | 3. Branch App Settings Management 23 | + [Retrieve existing app config](#getting-current-branch-app-config) 24 | + [Creating a New Branch App Config (DEPRECATED)](#creating-a-new-branch-app-config-deprecated) 25 | + [Updating an app config](#updating-a-branch-app-config) 26 | 27 | 4. Custom Events (deprecated) 28 | + [Create a custom events](#creating-custom-events) 29 | + [Create a custom commerce events](#creating-custom-commerce-events) 30 | 31 | ___ 32 | 33 | ## Creating a Deep Linking URL 34 | 35 | #### Endpoint 36 | 37 | POST /v1/url 38 | Content-Type: application/json 39 | 40 | #### Parameters 41 | 42 | **branch_key** _required_ 43 | : The Branch key of the originating app. 44 | 45 | ##### Functional 46 | 47 | **data** _optional_ 48 | : The dictionary to embed with the link. Accessed as session or install parameters from the SDK. **Use the data dictionary for all [link control parameters that you'll find here.](https://dev.branch.io/link_configuration/#redirect-customization)** 49 | 50 | **alias** _optional_ (max 128 characters) 51 | : Instead of our standard encoded short url, you can specify the alias of the link bnc.lt/devonaustin. Aliases are enforced to be unique per domain (bnc.lt, yourapp.com, etc). Be careful, link aliases are _unique_, immutable objects that cannot be deleted. 52 | 53 | NOTE: If you POST to the this endpoint with the same alias, and a matching set of other POST parameters to an existing aliased link, the original will be returned to you. If it clashes and you don't specify a match, will return a HTTP 409 error. 54 | 55 | **type** _optional_ 56 | : ADVANCED: 57 | - Set type to 1, to make the URL a one-time use URL. It won't deep link after 1 successful deep link. 58 | - *default* is set to 0, which is the standard Branch links created via our SDK.git 59 | 60 | **duration** _optional_ 61 | : ADVANCED: In seconds. Only set this key if you want to override the match duration for deep link matching. This is the time that Branch allows a click to remain outstanding and be eligible to be matched with a new app session. This is default set to 7200 (2 hours) 62 | 63 | ##### Tracking 64 | 65 | [**Branch analytics parameters**](https://dev.branch.io/link_configuration/#analytics-labels-for-data-organization) _optional_ It's important to tag your links with an organized structure of analytics labels so that the data appears consistent and readable in the dashboard. 66 | 67 | **identity** _optional_ (max 127 characters) 68 | : The identity used to identify the user. If the link is not tied to an identity, there's no need to specify an identity. 69 | 70 | #### Returns 71 | 72 | ```js 73 | { 74 | 'url': 'http://bnc.lt/l/deeplink-randomID' 75 | } 76 | ``` 77 | 78 | #### Example 79 | 80 | Here's an example cURL that you can paste into the terminal 81 | 82 | ```sh 83 | curl -X POST \ 84 | \ 85 | -H "Content-Type: application/json" \ 86 | \ 87 | -d '{"branch_key":"key_live_feebgAAhbH9Tv85H5wLQhpdaefiZv5Dv", "campaign":"new_product_annoucement", "channel":"email", "tags":["monday", "test123"], "data":"{\"name\": \"devon\", \"email\": \"devon@branch.io\", \"user_id\": \"12346\", \"$deeplink_path\": \"article/jan/123\", \"$desktop_url\": \"https://branch.io\"}"}' \ 88 | \ 89 | https://api2.branch.io/v1/url 90 | ``` 91 | 92 | ___ 93 | 94 | ## Bulk creating Deep Linking URLs 95 | 96 | For more details on how to create links, see the [Branch link creation guide](https://dev.branch.io/link_creation_guide/) 97 | 98 | #### Endpoint 99 | 100 | ```sh 101 | POST /v1/url/bulk/:branch_key 102 | Content-Type: application/json 103 | ``` 104 | 105 | #### Parameters 106 | 107 | A json array of pramameters from [Creating a Deep Linking URL.](https://dev.branch.io/link_creation_guide/) (Note: there is a 100KB limit on the request payload size) 108 | 109 | ```js 110 | [ 111 | { "channel": "branch" }, 112 | { "channel": "fb", "data": "{ \"$og_title\": \"deep linking\" }" } 113 | ] 114 | ``` 115 | 116 | #### Returns 117 | 118 | An array of deep linking urls and/or errors in case invalid params. 119 | 120 | ```js 121 | [ 122 | { 'url': 'http://bnc.lt/l/deeplink-randomID' }, 123 | { 'error': 'error message' } // in case of error 124 | ] 125 | ``` 126 | ___ 127 | 128 | ## Modifying Existing Deep Linking URLs 129 | 130 | We've exposed an endpoint to update a certain category of Branch links through our API. Simply issue a PUT to our v1/url endpoint. Certain links may not be updated, which are /c/ and /d/ links. 131 | 132 | #### Endpoint 133 | ```sh 134 | PUT /v1/url?url= 135 | Content-Type: application/json 136 | ``` 137 | 138 | #### Parameters 139 | 140 | **branch_key** _required_ 141 | : The Branch key of the originating app. Found in the Branch Dashboard under **Settings**. 142 | 143 | **branch_secret** _required_ 144 | : The paired Branch Secret to the Branch Key making the request. Found in the Branch Dashboard under **Settings**. 145 | 146 | **url** _required_ 147 | : The URL you want to modify, including the host and domain, ex: https://bnc.lt/m/abcd1234, this is included on the URL to request itself: 148 | 149 | PUT https://api2.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Ftest 150 | 151 | **analytics/tracking parameters** _optional_ 152 | 153 | : [**Branch analytics parameters**](https://dev.branch.io/link_configuration/#analytics-labels-for-data-organization). Use these keys inside the body of the PUT (NOT inside the 'data' key) to modify data such as channel, campaign, tags, and more. 154 | 155 | **data** _optional_ 156 | 157 | : The dictionary to embed with the link. Accessed as session or install parameters from the SDK. **Use the data dictionary for all [link control parameters that you'll find here.](https://dev.branch.io/link_configuration/#redirect-customization)** 158 | 159 | #### Example 160 | 161 | If you have a link with a URL of https://bnc.lt/test-link, a *channel* of 'facebook', and *data* of `{ "photo_id" : "50", "valid": "true" }` and want to update the channel, add an extra value to the dictionary, and add a campaign, here's how that would look: 162 | 163 | PUT https://api2.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Ftest-link 164 | 165 | { 166 | "branch_key" : "key_live_xxxx", 167 | "branch_secret": "secret_live_xxxx", 168 | "channel": "twitter", 169 | "campaign": "twitter-november-campaign", 170 | "data": { 171 | "photo_id": "51", 172 | "photo_name": "John Smith", 173 | "$og_image_url": "https://imgur.com/abcd" 174 | } 175 | } 176 | 177 | #### Returns 178 | 179 | The new link returns existing data of the link plus the newly added data of the link. Following the example above, this is what would return. 180 | 181 | ```js 182 | { 183 | "channel": "twitter", 184 | "campaign": "twitter-november-campaign", 185 | "feature": "share-button", 186 | "data": { 187 | "photo_id": "51", 188 | "valid": "true", 189 | "photo_name": "John Smith", 190 | "$og_image_url": "https://imgur.com/abcd", 191 | "~id": "123456789", 192 | "url": "https://bnc.lt/test-link" 193 | }, 194 | "alias": "test-link", 195 | "type": 0 196 | } 197 | ``` 198 | 199 | Note, some of this data is existing link data, and some is updated data, but the response will return all data. 200 | 201 | #### Restrictions 202 | 203 | There are certain restrictions when attempting to update links: 204 | - Not all links are updateable, namely links with the structure of `bnc.lt/c/` or `bnc.lt/d/` 205 | - The alias of a link cannot be updated, e.g. 'https://bnc.lt/test' -> 'https://bnc.lt/test1' 206 | - The identity associated with a Branch link cannot be updated 207 | - The `type` of a link cannot be changed, e.g. a marketing link is type 2, and a standard link generated by our Branch SDK is type 0 208 | - The following additional fields cannot be updated: 209 | - `app_id` 210 | - `identity_id` 211 | - `domain` 212 | - `state` 213 | - `creation_source` 214 | - `app_short_identifier` 215 | 216 | ___ 217 | 218 | ## Viewing State of Existing Deep Linking URLs 219 | 220 | We've exposed an endpoint to view the contents of Branch links through our API. Simply issue a GET to our v1/url endpoint with the URL you'd like to view. 221 | 222 | #### Endpoint 223 | ```sh 224 | GET /v1/url?url=&branch_key= 225 | ``` 226 | 227 | #### Parameters 228 | 229 | **branch_key** _required_ 230 | : The Branch key of the originating app. Found in the Branch Dashboard under **Settings**. 231 | 232 | **url** _required_ 233 | : The URL you want to modify, including the host and domain, ex: https://bnc.lt/m/abcd1234, this is included on the URL to request itself: 234 | 235 | #### Example 236 | 237 | If you have a link with a URL of `https://bnc.lt/m/7IhbRIjjmp` with Branch key of key_live_lceUuShIL0u4VHJv8BwEQmaitBfAXqCZ: 238 | 239 | GET https://api2.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Fm%2F7IhbRIjjmp&branch_key=key_live_lceUuShIL0u4VHJv8BwEQmaitBfAXqCZ 240 | 241 | 242 | #### Returns 243 | 244 | The new link returns existing data of the link. Following the example above, this is what would return. 245 | 246 | ```js 247 | { 248 | "channel": "twitter", 249 | "campaign": "twitter-november-campaign", 250 | "feature": "share-button", 251 | "data": { 252 | "photo_id": "51", 253 | "valid": "true", 254 | "photo_name": "John Smith", 255 | "$og_image_url": "https://imgur.com/abcd", 256 | "~id": "123456789", 257 | "url": "https://bnc.lt/test-link" 258 | }, 259 | "alias": "test-link", 260 | "type": 0 261 | } 262 | ``` 263 | 264 | --- 265 | 266 | ## Structuring a 'dynamic' deep link for app.link domains 267 | 268 | This should be used for situations where the longer link is okay and you want to create links quickly without a POST to the API. Here's a list of instructions on how to build a deep link: 269 | 270 | 1. Start with your Branch domain, http://yourapp.app.link. 271 | 2. [optional] Append the start of query params '?' 272 | 3. [optional] Append the Branch analytics tag to keep your data organized in the dashboard. ([list here](https://dev.branch.io/getting-started/configuring-links/guide/#analytics-labels)) *channel=email&tags[]=drip1&tags[]=welcome* 273 | 4. [optional] Append any custom deep link parameters &user_id=4562&name=devon&article_id=456 274 | 5. [optional] Append your Branch control parameters - see [a full list of them here](https://dev.branch.io/link_configuration/#redirect-customization) 275 | 276 | #### Endpoint 277 | 278 | ```sh 279 | GET https://yourapp.app.link?AnyOptionalQueryParamsBelow 280 | ``` 281 | 282 | > Example: 283 | https://branch.app.link?$deeplink_path=article%2Fjan%2F123&$fallback_url=https%3A%2F%2Fgoogle.com&channel=facebook&feature=affiliate 284 | 285 | #### Parameters 286 | 287 | For consistency, all parameters are kept in one spot since they are used for everything. Please find them in the [Link Configuration guide](https://dev.branch.io/getting-started/configuring-links/guide/) 288 | 289 | --- 290 | 291 | ## Structuring a 'dynamic' deep link for bnc.lt and custom domains 292 | 293 | This should be used for situations where the longer link is okay and you want to create links quickly without a POST to the API. Here's a list of instructions on how to build a deep link: 294 | 295 | 1. Start with your Branch domain, http://bnc.lt (or your white labeled one). 296 | 2. Append /a/your_Branch_key. 297 | 3. [optional] Append the start of query params '?' 298 | 4. [optional] Append the Branch analytics tag to keep your data organized in the dashboard. ([list here](https://dev.branch.io/getting-started/configuring-links/guide/#analytics-labels)) *channel=email&tags[]=drip1&tags[]=welcome* 299 | 5. [optional] Append any custom deep link parameters &user_id=4562&name=devon&article_id=456 300 | 6. [optional] Append your Branch control parameters - see [a full list of them here](https://dev.branch.io/link_configuration/#redirect-customization) 301 | 302 | #### Endpoint 303 | 304 | ```sh 305 | GET https://bnc.lt/a/?AnyOptionalQueryParamsBelow 306 | ``` 307 | 308 | > Example: 309 | https://bnc.lt/a/key_live_jbgnjxvlhSb6PGH23BhO4hiflcp3y7ky?$deeplink_path=article%2Fjan%2F123&$fallback_url=https%3A%2F%2Fgoogle.com&channel=facebook&feature=affiliate 310 | 311 | #### Parameters 312 | 313 | For consistency, all parameters are kept in one spot since they are used for everything. Please find them in the [Link Configuration guide](https://dev.branch.io/getting-started/configuring-links/guide/) 314 | 315 | ___ 316 | 317 | ## Logging Commerce Events 318 | 319 | #### Endpoint 320 | 321 | ```js 322 | POST /v2/event/standard 323 | Content-Type: application/json 324 | ``` 325 | 326 | #### Parameters 327 | 328 | Note about required identifiers. You must send up (in user_data): 329 | 1. developer_identity 330 | OR 331 | 2. browser_fingerprint_id 332 | OR 333 | 3. os=iOS AND (idfa OR idfv) 334 | OR 335 | 4. os=Android AND (android_id or aaid) 336 | 337 | -- 338 | 339 | *branch_key* _required_ 340 | : the app's branch_key 341 | 342 | *name* _required_ 343 | : one of ADD_TO_CART, ADD_TO_WISHLIST, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS 344 | 345 | *user_data.os* _required_ 346 | : one of "Android", "iOS" 347 | 348 | *user_data.os_version* 349 | : version of the operating system. Specific to Android and iOS. 350 | 351 | *user_data.environment* 352 | : usually FULL_APP. 353 | 354 | *user_data.aaid* 355 | : Android/Google advertising id 356 | 357 | *user_data.android_id* 358 | : Android hardware id 359 | 360 | *user_data.idfa* 361 | : iOS advertising id 362 | 363 | *user_data.idfv* 364 | : iOS vendor id 365 | 366 | *user_data.limit_ad_tracking* 367 | : true if the partner has opted to not be tracked by advertisers 368 | 369 | *user_data.user_agent* 370 | : user agent of the browser or app where the event occurred. Usually associated with a webview. 371 | 372 | *user_data.browser_fingerprint_id* 373 | : Branch internal-only field for tracking browsers 374 | 375 | *user_data.http_origin* 376 | : current page url where Web SDK logged web session start 377 | 378 | *user_data.http_referrer* 379 | : referral url that led to the current page where Web SDK logged web session start 380 | 381 | *user_data.developer_identity* 382 | : developer-specified identity for a user 383 | 384 | *user_data.country* 385 | : country code of the user, usually based on device settings or user agent string 386 | 387 | *user_data.language* 388 | : language code of the user, usually based on device settings or user agent string 389 | 390 | *user_data.local_ip* _Android only_ 391 | : local ip of the device 392 | 393 | *user_data.brand* 394 | : brand of the device 395 | 396 | *user_data.device_fingerprint_id* 397 | : Branch internal-only field for tracking devices 398 | 399 | *user_data.app_version* 400 | : app version downloaded by the user 401 | 402 | *user_data.model* 403 | : model of the device 404 | 405 | *user_data.screen_dpi* 406 | : screen's DPI 407 | 408 | *user_data.screen_height* 409 | : screen's height 410 | 411 | *user_data.screen_width* 412 | : screen's width 413 | 414 | *custom_data* 415 | : key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks. 416 | 417 | *event_data.transaction_id* 418 | : partner-specified transaction id for their internal use 419 | 420 | *event_data.revenue* 421 | : partner-specified reported revenue for the event 422 | 423 | *event_data.currency* 424 | : Currency that revenue, price, shipping, tax were orginally reported in by the partner 425 | 426 | *event_data.shipping* 427 | : Shipping cost associated with the transaction 428 | 429 | *event_data.tax* 430 | : Total tax associated with the transaction 431 | 432 | *event_data.coupon* 433 | : Transaction coupon redeemed with the transaction (e.g. "SPRING2017") 434 | 435 | *event_data.affiliation* 436 | : Store or affiliation from which this transaction occurred (e.g. Google Store) 437 | 438 | *event_data.description* 439 | : Description associated with the event, not necessarily specific to any individual content items (see below) 440 | 441 | *content_items[i].$content_schema* 442 | : category / schema for a piece of content. May be used in the future for analytics. One of: 443 | COMMERCE_AUCTION 444 | COMMERCE_BUSINESS 445 | COMMERCE_OTHER 446 | COMMERCE_PRODUCT 447 | COMMERCE_RESTAURANT 448 | COMMERCE_SERVICE 449 | COMMERCE_TRAVEL_FLIGHT 450 | COMMERCE_TRAVEL_HOTEL 451 | COMMERCE_TRAVEL_OTHER 452 | GAME_STATE 453 | MEDIA_IMAGE 454 | MEDIA_MIXED 455 | MEDIA_MUSIC 456 | MEDIA_OTHER 457 | MEDIA_VIDEO 458 | OTHER 459 | TEXT_ARTICLE 460 | TEXT_BLOG 461 | TEXT_OTHER 462 | TEXT_RECIPE 463 | TEXT_REVIEW 464 | TEXT_SEARCH_RESULTS 465 | TEXT_STORY 466 | TEXT_TECHNICAL_DOC 467 | 468 | *content_items[i].$og_title* 469 | : title (for the individual content item) 470 | 471 | *content_items[i].$og_description* 472 | : description (for individual content item) 473 | 474 | *content_items[i].$og_image_url* 475 | : image URL (for the individual content item) 476 | 477 | *content_items[i].$canonical_identifier* 478 | : used to allow Branch to unify content/messages for Content Analytics 479 | 480 | *content_items[i].$publicly_indexable* 481 | : `true`: content can be seen by anyone | `false`: cannot index for public use 482 | 483 | *content_items[i].$locally_indexable* 484 | : `true`: content can be indexed for local (device) use | `false`: cannot index for local use 485 | 486 | *content_items[i].$price* 487 | : price for the product/content 488 | 489 | *content_items[i].$quantity* 490 | : quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc) 491 | 492 | *content_items[i].$sku* 493 | : product sku or product id 494 | 495 | *content_items[i].$product_name* 496 | : product's name 497 | 498 | *content_items[i].$product_brand* 499 | : product's brand 500 | 501 | *content_items[i].$product_category* 502 | : product's category, if it's a product. One of: 503 | ANIMALS_AND_PET_SUPPLIES 504 | APPAREL_AND_ACCESSORIES 505 | ARTS_AND_ENTERTAINMENT 506 | BABY_AND_TODDLER 507 | BUSINESS_AND_INDUSTRIAL 508 | CAMERAS_AND_OPTICS 509 | ELECTRONICS 510 | FOOD_BEVERAGES_AND_TOBACCO 511 | FURNITURE 512 | HARDWARE 513 | HEALTH_AND_BEAUTY 514 | HOME_AND_GARDEN 515 | LUGGAGE_AND_BAGS 516 | MATURE 517 | MEDIA 518 | OFFICE_SUPPLIES 519 | RELIGIOUS_AND_CEREMONIAL 520 | SOFTWARE 521 | SPORTING_GOODS 522 | TOYS_AND_GAMES 523 | VEHICLES_AND_PARTS 524 | 525 | *content_items[i].$product_variant* 526 | : product's variant (e.g. XL, red) 527 | 528 | *content_items[i].$rating_average* 529 | : average rating of the item 530 | 531 | *content_items[i].$rating_count* 532 | : number of ratings for the item 533 | 534 | *content_items[i].$rating_max* 535 | : maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating) 536 | 537 | *content_items[i].$creation_timestamp* 538 | : time the content was created 539 | 540 | *content_items[i].$exp_date* 541 | : the last time afterwhich this content is no longer valid. null / 0 mean no limit. Should rarely be set. 542 | 543 | *content_items[i].$keywords* 544 | : keywords 545 | 546 | *content_items[i].$address_street* 547 | : street address for a restaurant, business, room (hotel), etc 548 | 549 | *content_items[i].$address_city* 550 | : street address for a restaurant, business, room (hotel), etc 551 | 552 | *content_items[i].$address_region* 553 | : state or region for a restaurant, business, room (hotel), etc 554 | 555 | *content_items[i].$address_country* 556 | : country code for a restaurant, business, room (hotel), etc 557 | 558 | *content_items[i].$address_postal_code* 559 | : postal/zip code for a restaurant, business, room (hotel), etc 560 | 561 | *content_items[i].$latitude* 562 | : latitude for a restaurant, business, room (hotel), etc 563 | 564 | *content_items[i].$longitude* 565 | : longitude for a restaurant, business, room (hotel), etc 566 | 567 | *content_items[i].$image_captions* 568 | : captions associated with the image 569 | 570 | *content_items[i].$condition* 571 | : For auctions, whether the item is new, good, acceptable, etc. One of: 572 | OTHER 573 | NEW 574 | EXCELLENT 575 | GOOD 576 | FAIR 577 | POOR 578 | USED 579 | REFURBISHED 580 | 581 | *content_items[i].$custom_fields* 582 | : key-value pairs that the app developer would like attached to the content item. Attached to events that are retrieved via Exports and sent via Webhooks. 583 | 584 | *metadata* 585 | : internal use only 586 | 587 | 588 | #### Request 589 | 590 | ```bash 591 | curl -vvv -d '{ 592 | "name": "PURCHASE", 593 | "customer_event_alias": "my custom alias", 594 | "user_data": { 595 | "os": "Android", 596 | "os_version": 25, 597 | "environment": "FULL_APP", 598 | "aaid": "abcdabcd-0123-0123-00f0-000000000000", 599 | "android_id": "a12300000000", 600 | "limit_ad_tracking": false, 601 | "developer_identity": "user123", 602 | "country": "US", 603 | "language": "en", 604 | "local_ip": "192.168.1.2", 605 | "brand": "LGE", 606 | "app_version": "1.0.0", 607 | "model": "Nexus 5X", 608 | "screen_dpi": 420, 609 | "screen_height": 1794, 610 | "screen_width": 1080 611 | }, 612 | "custom_data": { 613 | "purchase_loc": "Palo Alto", 614 | "store_pickup": "unavailable" 615 | }, 616 | "event_data": { 617 | "transaction_id": "tras_Id_1232343434", 618 | "currency": "USD", 619 | "revenue": 180.2, 620 | "shipping": 10.5, 621 | "tax": 13.5, 622 | "coupon": "promo-1234", 623 | "affiliation": "high_fi", 624 | "description": "Preferred purchase" 625 | }, 626 | "content_items": [ 627 | { 628 | "$content_schema": "COMMERCE_PRODUCT", 629 | "$og_title": "Nike Shoe", 630 | "$og_description": "Start loving your steps", 631 | "$og_image_url": "http://example.com/img1.jpg", 632 | "$canonical_identifier": "nike/1234", 633 | "$publicly_indexable": false, 634 | "$price": 101.2, 635 | "$locally_indexable": true, 636 | "$quantity": 1, 637 | "$sku": "1101123445", 638 | "$product_name": "Runner", 639 | "$product_brand": "Nike", 640 | "$product_category": "Sporting Goods", 641 | "$product_variant": "XL", 642 | "$rating_average": 4.2, 643 | "$rating_count": 5, 644 | "$rating_max": 2.2, 645 | "$creation_timestamp": 1499892854966, 646 | "$exp_date": 1499892854966, 647 | "$keywords": [ 648 | "sneakers", 649 | "shoes" 650 | ], 651 | "$address_street": "230 South LaSalle Street", 652 | "$address_city": "Chicago", 653 | "$address_region": "IL", 654 | "$address_country": "US", 655 | "$address_postal_code": "60604", 656 | "$latitude": 12.07, 657 | "$longitude": -97.5, 658 | "$image_captions": [ 659 | "my_img_caption1", 660 | "my_img_caption_2" 661 | ], 662 | "$condition": "NEW", 663 | "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}" 664 | }, 665 | { 666 | "$og_title": "Nike Woolen Sox", 667 | "$canonical_identifier": "nike/5324", 668 | "$og_description": "Fine combed woolen sox for those who love your foot", 669 | "$publicly_indexable": false, 670 | "$price": 80.2, 671 | "$locally_indexable": true, 672 | "$quantity": 5, 673 | "$sku": "110112467", 674 | "$product_name": "Woolen Sox", 675 | "$product_brand": "Nike", 676 | "$product_category": "Apparel & Accessories", 677 | "$product_variant": "Xl", 678 | "$rating_average": 3.3, 679 | "$rating_count": 5, 680 | "$rating_max": 2.8, 681 | "$creation_timestamp": 1499892854966 682 | } 683 | ], 684 | "metadata": {}, 685 | "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc" 686 | }' https://api2.branch.io/v2/event/standard 687 | ``` 688 | 689 | #### Response 690 | 691 | ```bash 692 | { "branch_view_enabled": true/false } 693 | ``` 694 | 695 | ___ 696 | 697 | ## Logging Content Events 698 | 699 | #### Endpoint 700 | 701 | ```js 702 | POST /v2/event/standard 703 | Content-Type: application/json 704 | ``` 705 | 706 | #### Parameters 707 | 708 | Note about required identifiers. You must send up (in user_data): 709 | 1. developer_identity 710 | OR 711 | 2. browser_fingerprint_id 712 | OR 713 | 3. os=iOS AND (idfa OR idfv) 714 | OR 715 | 4. os=Android AND (android_id or aaid) 716 | 717 | -- 718 | 719 | *branch_key* _required_ 720 | : the app's branch_key 721 | 722 | *name* _required_ 723 | : one of SEARCH, VIEW_ITEM, VIEW_ITEMS, RATE, SHARE 724 | 725 | *user_data.os* _required_ 726 | : one of "Android", "iOS" 727 | 728 | *user_data.os_version* 729 | : version of the operating system. Specific to Android and iOS. 730 | 731 | *user_data.environment* 732 | : usually FULL_APP. 733 | 734 | *user_data.aaid* 735 | : Android/Google advertising id 736 | 737 | *user_data.android_id* 738 | : Android hardware id 739 | 740 | *user_data.idfa* 741 | : iOS advertising id 742 | 743 | *user_data.idfv* 744 | : iOS vendor id 745 | 746 | *user_data.limit_ad_tracking* 747 | : true if the partner has opted to not be tracked by advertisers 748 | 749 | *user_data.user_agent* 750 | : user agent of the browser or app where the event occurred. Usually associated with a webview. 751 | 752 | *user_data.browser_fingerprint_id* 753 | : Branch internal-only field for tracking browsers 754 | 755 | *user_data.http_origin* 756 | : current page url where Web SDK logged web session start 757 | 758 | *user_data.http_referrer* 759 | : referral url that led to the current page where Web SDK logged web session start 760 | 761 | *user_data.developer_identity* 762 | : developer-specified identity for a user 763 | 764 | *user_data.country* 765 | : country code of the user, usually based on device settings or user agent string 766 | 767 | *user_data.language* 768 | : language code of the user, usually based on device settings or user agent string 769 | 770 | *user_data.local_ip* _Android only_ 771 | : local ip of the device 772 | 773 | *user_data.brand* 774 | : brand of the device 775 | 776 | *user_data.device_fingerprint_id* 777 | : Branch internal-only field for tracking devices 778 | 779 | *user_data.app_version* 780 | : app version downloaded by the user 781 | 782 | *user_data.model* 783 | : model of the device 784 | 785 | *user_data.screen_dpi* 786 | : screen's DPI 787 | 788 | *user_data.screen_height* 789 | : screen's height 790 | 791 | *user_data.screen_width* 792 | : screen's width 793 | 794 | *custom_data* 795 | : key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks. 796 | 797 | *event_data.search_query* 798 | : Search query associated with the event 799 | 800 | *event_data.description* 801 | : Description associated with the event, not necessarily specific to any individual content items (see below) 802 | 803 | *content_items[i].$content_schema* 804 | : category / schema for a piece of content. May be used in the future for analytics. One of: 805 | COMMERCE_AUCTION 806 | COMMERCE_BUSINESS 807 | COMMERCE_OTHER 808 | COMMERCE_PRODUCT 809 | COMMERCE_RESTAURANT 810 | COMMERCE_SERVICE 811 | COMMERCE_TRAVEL_FLIGHT 812 | COMMERCE_TRAVEL_HOTEL 813 | COMMERCE_TRAVEL_OTHER 814 | GAME_STATE 815 | MEDIA_IMAGE 816 | MEDIA_MIXED 817 | MEDIA_MUSIC 818 | MEDIA_OTHER 819 | MEDIA_VIDEO 820 | OTHER 821 | TEXT_ARTICLE 822 | TEXT_BLOG 823 | TEXT_OTHER 824 | TEXT_RECIPE 825 | TEXT_REVIEW 826 | TEXT_SEARCH_RESULTS 827 | TEXT_STORY 828 | TEXT_TECHNICAL_DOC 829 | 830 | *content_items[i].$og_title* 831 | : title (for the individual content item) 832 | 833 | *content_items[i].$og_description* 834 | : description (for individual content item) 835 | 836 | *content_items[i].$og_image_url* 837 | : image URL (for the individual content item) 838 | 839 | *content_items[i].$canonical_identifier* 840 | : used to allow Branch to unify content/messages for Content Analytics 841 | 842 | *content_items[i].$publicly_indexable* 843 | : `true`: content can be seen by anyone | `false`: cannot index for public use 844 | 845 | *content_items[i].$locally_indexable* 846 | : `true`: content can be indexed for local (device) use | `false`: cannot index for local use 847 | 848 | *content_items[i].$price* 849 | : price for the product/content 850 | 851 | *content_items[i].$sku* 852 | : product sku or product id 853 | 854 | *content_items[i].$product_name* 855 | : product's name 856 | 857 | *content_items[i].$product_brand* 858 | : product's brand 859 | 860 | *content_items[i].$product_category* 861 | : product's category, if it's a product. One of: 862 | ANIMALS_AND_PET_SUPPLIES 863 | APPAREL_AND_ACCESSORIES 864 | ARTS_AND_ENTERTAINMENT 865 | BABY_AND_TODDLER 866 | BUSINESS_AND_INDUSTRIAL 867 | CAMERAS_AND_OPTICS 868 | ELECTRONICS 869 | FOOD_BEVERAGES_AND_TOBACCO 870 | FURNITURE 871 | HARDWARE 872 | HEALTH_AND_BEAUTY 873 | HOME_AND_GARDEN 874 | LUGGAGE_AND_BAGS 875 | MATURE 876 | MEDIA 877 | OFFICE_SUPPLIES 878 | RELIGIOUS_AND_CEREMONIAL 879 | SOFTWARE 880 | SPORTING_GOODS 881 | TOYS_AND_GAMES 882 | VEHICLES_AND_PARTS 883 | 884 | *content_items[i].$product_variant* 885 | : product's variant (e.g. XL, red) 886 | 887 | *content_items[i].$rating_average* 888 | : average rating of the item 889 | 890 | *content_items[i].$rating_count* 891 | : number of ratings for the item 892 | 893 | *content_items[i].$rating_max* 894 | : maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating) 895 | 896 | *content_items[i].$creation_timestamp* 897 | : time the content was created 898 | 899 | *content_items[i].$exp_date* 900 | : the last time afterwhich this content is no longer valid. null / 0 mean no limit. Should rarely be set. 901 | 902 | *content_items[i].$keywords* 903 | : keywords 904 | 905 | *content_items[i].$address_street* 906 | : street address for a restaurant, business, room (hotel), etc 907 | 908 | *content_items[i].$address_city* 909 | : street address for a restaurant, business, room (hotel), etc 910 | 911 | *content_items[i].$address_region* 912 | : state or region for a restaurant, business, room (hotel), etc 913 | 914 | *content_items[i].$address_country* 915 | : country code for a restaurant, business, room (hotel), etc 916 | 917 | *content_items[i].$address_postal_code* 918 | : postal/zip code for a restaurant, business, room (hotel), etc 919 | 920 | *content_items[i].$latitude* 921 | : latitude for a restaurant, business, room (hotel), etc 922 | 923 | *content_items[i].$longitude* 924 | : longitude for a restaurant, business, room (hotel), etc 925 | 926 | *content_items[i].$image_captions* 927 | : captions associated with the image 928 | 929 | *content_items[i].$condition* 930 | : For auctions, whether the item is new, good, acceptable, etc. One of: 931 | OTHER 932 | NEW 933 | EXCELLENT 934 | GOOD 935 | FAIR 936 | POOR 937 | USED 938 | REFURBISHED 939 | 940 | *content_items[i].$custom_fields* 941 | : key-value pairs that the app developer would like attached to the content item. Attached to events that are retrieved via Exports and sent via Webhooks. 942 | 943 | *metadata* 944 | : internal use only 945 | 946 | 947 | #### Request 948 | 949 | ```bash 950 | curl -vvv -d '{ 951 | "name": "VIEW_ITEMS", 952 | "customer_event_alias": "my custom alias", 953 | "user_data": { 954 | "os": "Android", 955 | "os_version": 25, 956 | "environment": "FULL_APP", 957 | "aaid": "abcdabcd-0123-0123-00f0-000000000000", 958 | "android_id": "a12300000000", 959 | "limit_ad_tracking": false, 960 | "developer_identity": "user123", 961 | "country": "US", 962 | "language": "en", 963 | "local_ip": "192.168.1.2", 964 | "brand": "LGE", 965 | "app_version": "1.0.0", 966 | "model": "Nexus 5X", 967 | "screen_dpi": 420, 968 | "screen_height": 1794, 969 | "screen_width": 1080 970 | }, 971 | "custom_data": { 972 | "purchase_loc": "Palo Alto", 973 | "store_pickup": "unavailable" 974 | }, 975 | "event_data": { 976 | "search_query": "red sneakers", 977 | "description": "Preferred purchase" 978 | }, 979 | "content_items": [ 980 | { 981 | "$content_schema": "COMMERCE_PRODUCT", 982 | "$og_title": "Nike Shoe", 983 | "$og_description": "Start loving your steps", 984 | "$og_image_url": "http://example.com/img1.jpg", 985 | "$canonical_identifier": "nike/1234", 986 | "$publicly_indexable": false, 987 | "$price": 101.2, 988 | "$locally_indexable": true, 989 | "$sku": "1101123445", 990 | "$product_name": "Runner", 991 | "$product_brand": "Nike", 992 | "$product_category": "Sporting Goods", 993 | "$product_variant": "XL", 994 | "$rating_average": 4.2, 995 | "$rating_count": 5, 996 | "$rating_max": 2.2, 997 | "$creation_timestamp": 1499892854966, 998 | "$exp_date": 1499892854966, 999 | "$keywords": [ 1000 | "sneakers", 1001 | "shoes" 1002 | ], 1003 | "$address_street": "230 South LaSalle Street", 1004 | "$address_city": "Chicago", 1005 | "$address_region": "IL", 1006 | "$address_country": "US", 1007 | "$address_postal_code": "60604", 1008 | "$latitude": 12.07, 1009 | "$longitude": -97.5, 1010 | "$image_captions": [ 1011 | "my_img_caption1", 1012 | "my_img_caption_2" 1013 | ], 1014 | "$condition": "NEW", 1015 | "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}" 1016 | }, 1017 | { 1018 | "$og_title": "Nike Woolen Sox", 1019 | "$canonical_identifier": "nike/5324", 1020 | "$og_description": "Fine combed woolen sox for those who love your foot", 1021 | "$publicly_indexable": false, 1022 | "$price": 80.2, 1023 | "$locally_indexable": true, 1024 | "$sku": "110112467", 1025 | "$product_name": "Woolen Sox", 1026 | "$product_brand": "Nike", 1027 | "$product_category": "Apparel & Accessories", 1028 | "$product_variant": "Xl", 1029 | "$rating_average": 3.3, 1030 | "$rating_count": 5, 1031 | "$rating_max": 2.8, 1032 | "$creation_timestamp": 1499892854966 1033 | } 1034 | ], 1035 | "metadata": {}, 1036 | "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc" 1037 | }' https://api.branch.io/v2/event/standard 1038 | ``` 1039 | 1040 | #### Response 1041 | 1042 | ```bash 1043 | { "branch_view_enabled": true/false } 1044 | ``` 1045 | ___ 1046 | 1047 | ## Logging User Lifecycle Events 1048 | 1049 | #### Endpoint 1050 | 1051 | ```js 1052 | POST /v2/event/standard 1053 | Content-Type: application/json 1054 | ``` 1055 | 1056 | #### Parameters 1057 | 1058 | Note about required identifiers. You must send up (in user_data): 1059 | 1. developer_identity 1060 | OR 1061 | 2. browser_fingerprint_id 1062 | OR 1063 | 3. os=iOS AND (idfa OR idfv) 1064 | OR 1065 | 4. os=Android AND (android_id or aaid) 1066 | 1067 | -- 1068 | 1069 | *branch_key* _required_ 1070 | : the app's branch_key 1071 | 1072 | *name* _required_ 1073 | : one of SEARCH, VIEW_CONTENT, VIEW_CONTENT_LIST, RATE, SHARE_CONTENT_ITEM 1074 | 1075 | *user_data.os* _required_ 1076 | : one of "Android", "iOS" 1077 | 1078 | *user_data.os_version* 1079 | : version of the operating system. Specific to Android and iOS. 1080 | 1081 | *user_data.environment* 1082 | : usually FULL_APP. 1083 | 1084 | *user_data.aaid* 1085 | : Android/Google advertising id 1086 | 1087 | *user_data.android_id* 1088 | : Android hardware id 1089 | 1090 | *user_data.idfa* 1091 | : iOS advertising id 1092 | 1093 | *user_data.idfv* 1094 | : iOS vendor id 1095 | 1096 | *user_data.limit_ad_tracking* 1097 | : true if the partner has opted to not be tracked by advertisers 1098 | 1099 | *user_data.user_agent* 1100 | : user agent of the browser or app where the event occurred. Usually associated with a webview. 1101 | 1102 | *user_data.browser_fingerprint_id* 1103 | : Branch internal-only field for tracking browsers 1104 | 1105 | *user_data.http_origin* 1106 | : current page url where Web SDK logged web session start 1107 | 1108 | *user_data.http_referrer* 1109 | : referral url that led to the current page where Web SDK logged web session start 1110 | 1111 | *user_data.developer_identity* 1112 | : developer-specified identity for a user 1113 | 1114 | *user_data.country* 1115 | : country code of the user, usually based on device settings or user agent string 1116 | 1117 | *user_data.language* 1118 | : language code of the user, usually based on device settings or user agent string 1119 | 1120 | *user_data.local_ip* _Android only_ 1121 | : local ip of the device 1122 | 1123 | *user_data.brand* 1124 | : brand of the device 1125 | 1126 | *user_data.device_fingerprint_id* 1127 | : Branch internal-only field for tracking devices 1128 | 1129 | *user_data.app_version* 1130 | : app version downloaded by the user 1131 | 1132 | *user_data.model* 1133 | : model of the device 1134 | 1135 | *user_data.screen_dpi* 1136 | : screen's DPI 1137 | 1138 | *user_data.screen_height* 1139 | : screen's height 1140 | 1141 | *user_data.screen_width* 1142 | : screen's width 1143 | 1144 | *custom_data* 1145 | : key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks. 1146 | 1147 | *event_data.description* 1148 | : Description associated with the event, not necessarily specific to any individual content items (see below) 1149 | 1150 | *metadata* 1151 | : internal use only 1152 | 1153 | 1154 | #### Request 1155 | 1156 | ```bash 1157 | curl -vvv -d '{ 1158 | "name": "COMPLETE_REGISTRATION", 1159 | "user_data": { 1160 | "os": "Android", 1161 | "os_version": 25, 1162 | "environment": "FULL_APP", 1163 | "aaid": "abcdabcd-0123-0123-00f0-000000000000", 1164 | "android_id": "a12300000000", 1165 | "limit_ad_tracking": false, 1166 | "developer_identity": "user123", 1167 | "country": "US", 1168 | "language": "en", 1169 | "local_ip": "192.168.1.2", 1170 | "brand": "LGE", 1171 | "app_version": "1.0.0", 1172 | "model": "Nexus 5X", 1173 | "screen_dpi": 420, 1174 | "screen_height": 1794, 1175 | "screen_width": 1080 1176 | }, 1177 | "custom_data": { 1178 | "foo": "bar" 1179 | }, 1180 | "event_data": { 1181 | "description": "Preferred purchase" 1182 | }, 1183 | "metadata": {}, 1184 | "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc" 1185 | }' https://api.branch.io/v2/event/standard 1186 | ``` 1187 | 1188 | #### Response 1189 | 1190 | ```bash 1191 | { "branch_view_enabled": true/false } 1192 | ``` 1193 | 1194 | ___ 1195 | 1196 | ## Logging Custom Events 1197 | 1198 | #### Endpoint 1199 | 1200 | ```js 1201 | POST /v2/event/custom 1202 | Content-Type: application/json 1203 | ``` 1204 | 1205 | #### Parameters 1206 | 1207 | Note about required identifiers. You must send up (in user_data): 1208 | 1. developer_identity 1209 | OR 1210 | 2. browser_fingerprint_id 1211 | OR 1212 | 3. os=iOS AND (idfa OR idfv) 1213 | OR 1214 | 4. os=Android AND (android_id or aaid) 1215 | 1216 | -- 1217 | 1218 | *branch_key* _required_ 1219 | : the app's branch_key 1220 | 1221 | *name* _required_ 1222 | : string for custom event name 1223 | 1224 | *user_data.os* _required_ 1225 | : one of "Android", "iOS" 1226 | 1227 | *user_data.os_version* 1228 | : version of the operating system. Specific to Android and iOS. 1229 | 1230 | *user_data.environment* 1231 | : usually FULL_APP. 1232 | 1233 | *user_data.aaid* 1234 | : Android/Google advertising id 1235 | 1236 | *user_data.android_id* 1237 | : Android hardware id 1238 | 1239 | *user_data.idfa* 1240 | : iOS advertising id 1241 | 1242 | *user_data.idfv* 1243 | : iOS vendor id 1244 | 1245 | *user_data.limit_ad_tracking* 1246 | : true if the partner has opted to not be tracked by advertisers 1247 | 1248 | *user_data.user_agent* 1249 | : user agent of the browser or app where the event occurred. Usually associated with a webview. 1250 | 1251 | *user_data.browser_fingerprint_id* 1252 | : Branch internal-only field for tracking browsers 1253 | 1254 | *user_data.http_origin* 1255 | : current page url where Web SDK logged web session start 1256 | 1257 | *user_data.http_referrer* 1258 | : referral url that led to the current page where Web SDK logged web session start 1259 | 1260 | *user_data.developer_identity* 1261 | : developer-specified identity for a user 1262 | 1263 | *user_data.country* 1264 | : country code of the user, usually based on device settings or user agent string 1265 | 1266 | *user_data.language* 1267 | : language code of the user, usually based on device settings or user agent string 1268 | 1269 | *user_data.local_ip* _Android only_ 1270 | : local ip of the device 1271 | 1272 | *user_data.brand* 1273 | : brand of the device 1274 | 1275 | *user_data.device_fingerprint_id* 1276 | : Branch internal-only field for tracking devices 1277 | 1278 | *user_data.app_version* 1279 | : app version downloaded by the user 1280 | 1281 | *user_data.model* 1282 | : model of the device 1283 | 1284 | *user_data.screen_dpi* 1285 | : screen's DPI 1286 | 1287 | *user_data.screen_height* 1288 | : screen's height 1289 | 1290 | *user_data.screen_width* 1291 | : screen's width 1292 | 1293 | *custom_data* 1294 | : key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks. 1295 | 1296 | *metadata* 1297 | : internal use only 1298 | 1299 | 1300 | #### Request 1301 | 1302 | ```bash 1303 | curl -vvv -d '{ 1304 | "name": "picture swiped", 1305 | "customer_event_alias": "my custom alias", 1306 | "user_data": { 1307 | "os": "Android", 1308 | "os_version": 25, 1309 | "environment": "FULL_APP", 1310 | "aaid": "abcdabcd-0123-0123-00f0-000000000000", 1311 | "android_id": "a12300000000", 1312 | "limit_ad_tracking": false, 1313 | "developer_identity": "user123", 1314 | "country": "US", 1315 | "language": "en", 1316 | "local_ip": "192.168.1.2", 1317 | "brand": "LGE", 1318 | "app_version": "1.0.0", 1319 | "model": "Nexus 5X", 1320 | "screen_dpi": 420, 1321 | "screen_height": 1794, 1322 | "screen_width": 1080 1323 | }, 1324 | "custom_data": { 1325 | "foo": "bar" 1326 | }, 1327 | "metadata": {}, 1328 | "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc" 1329 | }' https://api.branch.io/v2/event/custom 1330 | ``` 1331 | 1332 | #### Response 1333 | 1334 | ```bash 1335 | { "branch_view_enabled": true/false } 1336 | ``` 1337 | 1338 | ___ 1339 | 1340 | ## Getting Current Branch App Config 1341 | 1342 | #### Endpoint 1343 | 1344 | GET /v1/app/[branch key]?branch_secret=[branch secret] 1345 | 1346 | #### Parameters 1347 | 1348 | **branch_key** _required_ 1349 | : The id of the app to retrieve. 1350 | 1351 | **branch_secret** _required_ 1352 | : The secret of the app to retrieve. 1353 | 1354 | #### Returns 1355 | 1356 | ```js 1357 | { 1358 | branch_key: "the app key", 1359 | branch_secret: "the app secret", 1360 | creation_date : "date app was created", 1361 | 1362 | app_name: "name of the app", 1363 | 1364 | dev_name: "main contact name", 1365 | dev_email: "main contact email", 1366 | dev_phone_number: "main contact phone", 1367 | 1368 | android_app: "whether an Android app is enabled", 1369 | android_url: "url of Android store, or namespace (com.android.myapp)", 1370 | android_uri_scheme: "the Android URI scheme", 1371 | android_package_name: "the Android package name", 1372 | sha256_cert_fingerprints: "the SHA256 fingerprints for App Links", 1373 | android_app_links_enabled: "whether App Links are enabled", 1374 | 1375 | ios_app: "whether an iOS app is enabled", 1376 | ios_url: "url of iOS store, or app id (id512451233)", 1377 | ios_uri_scheme: "the iOS URI scheme", 1378 | ios_store_country: "the country code of the app, default to US", 1379 | ios_bundle_id: "the iOS bundle ID", 1380 | ios_team_id: "the iOS Team ID", 1381 | universal_linking_enabled: "whether Universal Links are enabled", 1382 | 1383 | fire_url: "the redirect on Fire phones", 1384 | windows_phone_url: "the redirect on Windows phones", 1385 | blackberry_url: "The redirect on Blackberry phones", 1386 | web_url: "backup website if URLs are null", 1387 | default_desktop_url: "the default desktop redirect, or null if set to hosted SMS", 1388 | 1389 | short_url_domain: "white labeled domain for short links", 1390 | 1391 | text_message: "text message to use, {{ link }} will be replaced with short link", 1392 | 1393 | og_app_id: "optional default Open Graph (OG) app id", 1394 | og_title: "optional default OG title", 1395 | og_image_url: "optional default OG image URL", 1396 | og_description: "optional default OG description", 1397 | 1398 | deepview_desktop: "the current deepview selected for the desktop platform", 1399 | deepview_ios: "the current deepview selected for the iOS platform", 1400 | deepview_android: "the current deepview selected for the Android platform", 1401 | } 1402 | ``` 1403 | 1404 | ___ 1405 | 1406 | ## Creating a New Branch App Config (DEPRECATED) 1407 | 1408 | #### Endpoint 1409 | 1410 | ```js 1411 | POST /v1/app 1412 | Content-Type: application/json 1413 | ``` 1414 | 1415 | #### Parameters 1416 | 1417 | **user_id** _required_ 1418 | : The dashboard user id. Can be found on your [Branch Dashboard](https://dashboard.branch.io/settings/account) 1419 | 1420 | **app_name** _required_ (max 255 characters) 1421 | : The name of the app. 1422 | 1423 | **dev_name** _required_ (max 255 characters) 1424 | : The main contact developer name. 1425 | 1426 | **dev_email** _required_ (max 255 characters) 1427 | : The main contact developer email. 1428 | 1429 | Note: we'll send an invite message to this email upon account creation. 1430 | 1431 | **android_app** _optional_ 1432 | : Whether an Android app is enabled, (0 or 1 indicating present) 1433 | 1434 | **android_url** _optional_ 1435 | : The url of the Android store, or package name (com.android.myapp). `android_app` must be set to `2`. 1436 | 1437 | **android_uri_scheme** _optional_ 1438 | : The Android URI scheme. 1439 | 1440 | **android_package_name** _optional_ 1441 | : The Android package name (com.android.myapp) 1442 | 1443 | **sha256_cert_fingerprints** _optional_ 1444 | : The SHA256 fingerprints for App Links, in array form 1445 | 1446 | **android_app_links_enabled** _optional_ 1447 | : Whether App Links are enabled, (0 or 1 indicating true) 1448 | 1449 | **ios_app** _optional_ 1450 | : Whether an iOS app is enabled, (0 or 1 indicating present) 1451 | 1452 | **ios_url** _optional_ 1453 | : The url of iOS store, or app id (id512451233), or a fallback URL for iOS if present. `ios_app` must be set to `2`. 1454 | 1455 | **ios_uri_scheme** _optional_ 1456 | : The iOS URI scheme. 1457 | 1458 | **ios_store_country** _optional_ (max 255 characters) 1459 | : The country code of the app, default to 'US'. 1460 | 1461 | **ios_bundle_id** _optional_ 1462 | : The iOS bundle ID 1463 | 1464 | **ios_team_id** _optional_ 1465 | : The iOS Team ID 1466 | 1467 | **universal_linking_enabled** _optional_ 1468 | : Whether Universal Links should be enabled, (0 or 1 indicating true) 1469 | 1470 | **fire_url** _optional_ 1471 | : The redirect on Fire phones 1472 | 1473 | **windows_phone_url** _optional_ 1474 | : The redirect on Windows phones 1475 | 1476 | **blackberry_url** _optional_ 1477 | : The redirect on Blackberry phones 1478 | 1479 | **web_url** _optional_ 1480 | : Backup website if URLs are null. 1481 | 1482 | **default_desktop_url** _optional_ 1483 | : The default desktop redirect, or null if set to hosted SMS 1484 | 1485 | **text_message** _optional_ (max 255 characters) 1486 | : Text message to use for text-me feature, {{ link }} will be replaced with short link. 1487 | 1488 | **og_app_id** _optional_ (max 255 characters) 1489 | : Default Open Graph (OG) app id. 1490 | 1491 | **og_title** _optional_ (max 255 characters) 1492 | : Default OG title to be used with links. 1493 | 1494 | **og_description** _optional_ (max 255 characters) 1495 | : Default OG description to be used with links. 1496 | 1497 | **og_image_url** _optional_ (max 255 characters) 1498 | : Default OG image URL to be used with links. 1499 | 1500 | **deepview_desktop** _optional_ 1501 | : The current deepview selected for the desktop platform, (eg "default", "my_template") 1502 | 1503 | **deepview_ios** _optional_ 1504 | : The current deepview selected for the iOS platform, (eg "default", "my_template") 1505 | 1506 | **deepview_android** _optional_ 1507 | : The current deepview selected for the Android platform, (eg "default", "my_template") 1508 | 1509 | #### Request 1510 | 1511 | ```bash 1512 | curl -XPOST -d '{ 1513 | "user_id": "...", 1514 | "app_name": "eneff_test_3", 1515 | "dev_name": "...", 1516 | "dev_email": "...", 1517 | 1518 | "always_open_app": "1", 1519 | 1520 | "android_app": "2", 1521 | "android_url": "https://www.example.com/ios", 1522 | "android_uri_scheme": "branchtest://", 1523 | "android_package_name": "com.branch.test", 1524 | "android_app_links_enabled": "1", 1525 | "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"], 1526 | 1527 | "ios_app": "2", 1528 | "ios_url": "https://www.example.com/ios", 1529 | "ios_uri_scheme": "branchtest://", 1530 | "ios_store_country": "US", 1531 | "universal_linking_enabled": "1", 1532 | "ios_bundle_id": "com.branch.test", 1533 | "ios_team_id": "PW4Q8885U7", 1534 | 1535 | "fire_url": "https://www.example.com/amazon", 1536 | "windows_phone_url": "https://www.example.com/windows", 1537 | "blackberry_url": "https://www.example.com/blackberry", 1538 | "web_url": "https://www.example.com/web", 1539 | 1540 | "default_desktop_url": "https://www.example.com/desktop", 1541 | "text_message": "click here to download", 1542 | 1543 | "og_app_id": "branch 123", 1544 | "og_title": "branch test", 1545 | "og_description": "branch description", 1546 | "og_image_url": "http://lorempixel.com/400/400/", 1547 | 1548 | "deepview_desktop": "branch_default", 1549 | "deepview_ios": "branch_default", 1550 | "deepview_android": "branch_default" 1551 | }' 'https://api.branch.io/v1/app' 1552 | ``` 1553 | 1554 | #### Response 1555 | 1556 | ```bash 1557 | { 1558 | "id": "...", 1559 | "app_key": "...", 1560 | "creation_date": "2016-12-01T19:38:25.661Z", 1561 | "app_name": "eneff_test_3", 1562 | "origin": ...", 1563 | "dev_name": "...", 1564 | "dev_email": "...", 1565 | "always_open_app": "1", 1566 | "android_app": "2", 1567 | "android_url": "https://www.example.com/ios", 1568 | "android_uri_scheme": "branchtest://", 1569 | "android_package_name": "com.branch.test", 1570 | "android_app_links_enabled": "1", 1571 | "ios_app": "2", 1572 | "ios_url": "https://www.example.com/ios", 1573 | "ios_uri_scheme": "branchtest://", 1574 | "ios_store_country": "US", 1575 | "ios_bundle_id": "com.branch.test", 1576 | "ios_team_id": "PW4Q8885U7", 1577 | "universal_linking_enabled": "1", 1578 | "fire_url": "https://www.example.com/amazon", 1579 | "windows_phone_url": "https://www.example.com/windows", 1580 | "blackberry_url": "https://www.example.com/blackberry", 1581 | "web_url": "https://www.example.com/web", 1582 | "default_desktop_url": "https://www.example.com/desktop", 1583 | "short_url_domain": "", 1584 | "default_short_url_domain": "94h3.app.link", 1585 | "alternate_short_url_domain": "94h3-alternate.app.link", 1586 | "text_message": "click here to download", 1587 | "og_app_id": "branch 123", 1588 | "og_title": "branch test", 1589 | "og_image_url": "http://lorempixel.com/400/400/", 1590 | "og_description": "branch description", 1591 | "branch_key": "...", 1592 | "branch_secret": "...", 1593 | "deepview_desktop": "branch_default", 1594 | "deepview_ios": "branch_default", 1595 | "deepview_android": "branch_default" 1596 | } 1597 | ``` 1598 | 1599 | ___ 1600 | 1601 | ## Updating a Branch App Config 1602 | 1603 | #### Endpoint 1604 | 1605 | ```sh 1606 | PUT /v1/app/:branch_key 1607 | Content-Type: application/json 1608 | ``` 1609 | 1610 | #### Parameters 1611 | 1612 | **branch_secret** _required_ 1613 | : The branch secret of the app to modify. 1614 | 1615 | **app_name** _optional_ (max 255 characters) 1616 | : The name of the app. 1617 | 1618 | **dev_name** _required_ (max 255 characters) 1619 | : The main contact developer name. 1620 | 1621 | **dev_email** _required_ (max 255 characters) 1622 | : The main contact developer email. 1623 | 1624 | **android_url** _optional_ 1625 | : The url of the Android store, or package name (com.android.myapp). Note that to set a fallback URL for Android instead, you must also set `android_app` to `2`. 1626 | 1627 | **android_uri_scheme** _optional_ 1628 | : The Android URI scheme. 1629 | 1630 | **ios_url** _optional_ 1631 | : The url of iOS store, or app id (id512451233) 1632 | 1633 | **ios_uri_scheme** _optional_ 1634 | : The iOS URI scheme. 1635 | 1636 | **ios_store_country** _optional_ (max 255 characters) 1637 | : The country code of the app, default to US. 1638 | 1639 | **web_url** _optional_ 1640 | : Backup website if URLs are null. 1641 | 1642 | **text_message** _optional_ (max 255 characters) 1643 | : The text message to use for text-me feature, {{ link }} will be replaced with short link. 1644 | 1645 | **og_app_id** _optional_ (max 255 characters) 1646 | : Default Open Graph (OG) app id. 1647 | 1648 | **og_title** _optional_ (max 255 characters) 1649 | : Default OG title to be used with links. 1650 | 1651 | **og_description** _optional_ (max 255 characters) 1652 | : Default OG description to be used with links. 1653 | 1654 | **og_image_url** _optional_ (max 255 characters) 1655 | : Default OG image URL to be used with links. 1656 | 1657 | #### Returns 1658 | 1659 | ```js 1660 | { 1661 | branch_key: "the app key", 1662 | branch_secret: "the app secret", 1663 | creation_date : "date app was created", 1664 | 1665 | app_name: "name of the app", 1666 | 1667 | dev_name: "main contact name", 1668 | dev_email: "main contact email", 1669 | dev_phone_number: "main contact phone", 1670 | 1671 | android_url: "url of Android store, or namespace (com.android.myapp)", 1672 | android_uri_scheme: "the Android URI scheme", 1673 | 1674 | ios_url: "url of iOS store, or app id (id512451233)", 1675 | ios_uri_scheme: "the iOS URI scheme", 1676 | ios_store_country: "the country code of the app, default to US", 1677 | 1678 | web_url: "backup website if URLs are null", 1679 | 1680 | short_url_domain: "white labeled domain for short links", 1681 | 1682 | text_message: "text message to use, {{ link }} will be replaced with short link", 1683 | 1684 | og_app_id: "optional default Open Graph (OG) app id", 1685 | og_title: "optional default OG title", 1686 | og_image_url: "optional default OG image URL", 1687 | og_description: "optional default OG description" 1688 | } 1689 | ``` 1690 | ___ 1691 | 1692 | ## Creating Custom Events 1693 | 1694 | *DEPRECATED* 1695 | 1696 | This endpoint, /v1/event, is deprecated in favor of /v2/event. Please refer to these sections instead: 1697 | + [Logging a commerce event (purchase, add to cart, etc)](#logging-commerce-events) 1698 | + [Logging a content event (search, view content items, etc)](#logging-content-events) 1699 | + [Logging a user lifecycle event (complete registration, unlock achievement, etc)](#logging-user-lifecycle-events) 1700 | + [Logging other custom events](#logging-custom-events) 1701 | 1702 | #### Endpoint 1703 | 1704 | ```sh 1705 | POST /v1/event 1706 | Content-Type: application/json 1707 | ``` 1708 | 1709 | #### Parameters 1710 | 1711 | - **branch_key** _required_ 1712 | : The Branch key of the originating app. 1713 | 1714 | - **identity** _required_ (max 127 characters) 1715 | : The identity used to identify the user. 1716 | 1717 | - **event** _required_ (max 63 characters) 1718 | : The event to associate with this identity. 1719 | 1720 | - **metadata** _optional_ 1721 | : Any associated parameters to be stored with the event. 1 layer JSON format. (max 255 characters for both keys and values) 1722 | 1723 | #### Testing 1724 | 1725 | - [Branch Dashboard Liveview](https://dashboard.branch.io/liveview/events) 1726 | 1727 | #### Example 1728 | 1729 | ```sh 1730 | curl --request POST \ 1731 | --url https://api.branch.io/v1/event \ 1732 | --header 'cache-control: no-cache' \ 1733 | --header 'content-type: application/json' \ 1734 | --data '{ 1735 | "branch_key": "...", 1736 | "identity": "360202634827023565", 1737 | "event": "done", 1738 | "metadata": { 1739 | "hello": "world", 1740 | "custom_data": "this" 1741 | } 1742 | }' 1743 | ``` 1744 | 1745 | #### Returns 1746 | 1747 | ```sh 1748 | {} 1749 | ``` 1750 | 1751 | ___ 1752 | 1753 | ## Creating Custom Commerce Events 1754 | 1755 | *DEPRECATED* 1756 | 1757 | This endpoint, /v1/event, is deprecated in favor of /v2/event. Please refer to these sections instead: 1758 | + [Logging a commerce event (purchase, add to cart, etc)](#logging-commerce-events) 1759 | + [Logging a content event (search, view content items, etc)](#logging-content-events) 1760 | + [Logging a user lifecycle event (complete registration, unlock achievement, etc)](#logging-user-lifecycle-events) 1761 | + [Logging other custom events](#logging-custom-events) 1762 | 1763 | #### Endpoint 1764 | 1765 | ```sh 1766 | POST /v1/event 1767 | Content-Type: application/json 1768 | ``` 1769 | 1770 | #### Parameters 1771 | 1772 | - **branch_key** _required_ 1773 | : The Branch key of the originating app. 1774 | 1775 | - **identity** _required_ (max 127 characters) 1776 | : The identity used to identify the user. 1777 | 1778 | - **event** _required_ (max 63 characters) 1779 | : The event to associate with this identity. 1780 | 1781 | - **metadata** _optional_ 1782 | : Any associated parameters to be stored with the event. 1 layer JSON format. (max 255 characters for both keys and values) 1783 | 1784 | - **commerce_data** 1785 | : Any commerce parameters to be stored with the event. (max 255 characters for both keys and values) 1786 | 1787 | #### Testing 1788 | 1789 | - [Branch Dashboard Liveview](https://dashboard.branch.io/liveview/commerce_events) 1790 | 1791 | 1792 | #### Example 1793 | 1794 | ```sh 1795 | curl --request POST \ 1796 | --url https://api.branch.io/v1/event \ 1797 | --header 'cache-control: no-cache' \ 1798 | --header 'content-type: application/json' \ 1799 | --data '{ 1800 | "branch_key": "...", 1801 | "identity": "360202634827023565", 1802 | "event": "purchase", 1803 | "metadata": { 1804 | "hello": "world", 1805 | "custom_data": "this" 1806 | }, 1807 | "commerce_data": { 1808 | "revenue": 50.0, 1809 | "currency": "USD", 1810 | "transaction_id": "foo-transaction-id", 1811 | "shipping": 0.0, 1812 | "tax": 5.0, 1813 | "affiliation": "foo-affiliation", 1814 | "products": [ 1815 | { 1816 | "sku": "foo-sku-1", 1817 | "name": "foo-item-1", 1818 | "price": 45.00, 1819 | "quantity": 1, 1820 | "brand": "foo-brand", 1821 | "category": "Electronics", 1822 | "variant": "foo-variant-1" 1823 | }, 1824 | { 1825 | "sku": "foo-sku-2", 1826 | "price": 2.50, 1827 | "quantity": 2 1828 | } 1829 | ] 1830 | } 1831 | }' 1832 | ``` 1833 | 1834 | #### Returns 1835 | 1836 | ```sh 1837 | {} 1838 | ``` 1839 | --------------------------------------------------------------------------------