The network request to v1/open should occur when you are successfully notified the app was brought to the foreground. Branch defines an app lifecycle as a session of when your application is launched (cold start, or if it was present in the iOS or Android task manager), and comes to the device’s foreground.
The Branch Key of the originating app obtained in your Account Settings
The Branch secret of the originating app obtained in your Account Settings
REQUIRED Always set to true
Your app's version
Model of the device.
System OS. Only accepts Android or iOS
The version of the device's OS (e.g. “23” for Android or “9.1.2” for iOS respectively. Will accept any value, preferred default to “NA”. This cannot be blank.)
The user agent of the device
Set to false if the hardware_id property cannot be populated, otherwise default to true
A value used to determine whether the IDFA or GAID can be used for advertising purposes. If Limit Ad Tracking should be enabled, do not include in the request.
In iOS, populate with the IDFA if it's available, otherwise fallback to IDFV. On Android, populate with the ANDROID_ID (hardware id). If no device ID is available, do not include in request.
Valid for iOS ONLY. Value confirms whether the iOS ID in the hardware_id property is an "idfa" or "vendor_id" (do not include in request, if hardware_id is not populated)
iOS ONLY The IDFV if it's available, otherwise do not include in request.
Valid for ANDROID ONLY. The Google Advertising ID if it's available, otherwise do not include in request
ANDROID ONLY The set of Advertising IDs if it's available, otherwise do not include in request. Can include identifiers like OAID
This is the device's local IP address, if one is available. This is incremental to the falserequired IP header. An optional but highly recommended data metadata that improves attribution accuracy.
Height of the device’s screen. An optional but useful data metadata that improves attribution accuracy.
Width of the device’s screen. An optional but useful data metadata that improves attribution accuracy.
a URI opens the app, check for a link_click_id query, and populate with that value (if missing, do not include in request) link_click_id may also be sourced by the Google Install Referrer
Populate with a Branch or non-Branch web url that opened the app (if missing, do not include in request)
Populate with a Branch or non-Branch web url that opened the app (if missing, do not include in request)
Set to false to ensure we retrieve deep links from Facebook's deferred deep linking API (requires adding your Facebook App Secret to the Branch Dashboard)
Valid for ANDROID ONLY Populate it with the value of the full Android PlayStore Install Referrer URL. Only include in the app's first session, if it's available.
Valid for ANDROID ONLY The value of the google_search_install_referrer query parameter on the referrerUrl from the Google Install Referrer. Only include in the app's first session, if it's available.
Valid for ANDROID ONLY The referrer click timestamp collected from the Play Install Referrer library. Only include in the app's first session, if it's available.
Valid for ANDROID ONLY The install begin timestamp collected from the Play Install Referrer library. Only include in the app's first session, if it's available.
Valid for iOS ONLY Attribution Token used for Apple Search Ads . used to call the Apple Search Ads Attribution API. The token has a 24 hr TTL, so send to Branch within that time in order to use it for attribution.
Identifies if this is the first time the user opened the app. If true, Branch will check if we saw the user download the app before, and mark the session as a reinstall if yes, and an install if no. If this value was set to false, Branch will count the session as an open.
Setting to true enables the ability to set an randomized_bundle_token property in v1/open requests and returns a value in the response. Do not set this property in the request, if this feature will not be used.
If server_to_server_identity is true, Branch returns a new identity value in any request that does not set randomized_bundle_token. After the first request, this property must be hardcoded with the randomized_bundle_token received in the first network response. Failure to return this value in subsequent requests severely limits the ability to connect different events for that user.
If server_to_server_identity is true, this property can be used to associate a custom user ID with Branch's anonymous identity. (You should never use personal user information here, and all values should be encrypted before being passed to Branch.)[https://help.branch.io/using-branch/docs/best-practices-to-avoid-sending-pii-to-branch#section-developer-identity}
If set to true, Branch will not store any data from this app session. The network response can still return deep link data for processing, but no information will be stored afterwards.
If set to true, you can use the Branch Dashboard to selectively remove sessions with this flag (from being sent to ad networks)[https://help.branch.io/developers-hub/docs/filtering-ad-network-data#setting-the-event-flag-in-the-branch-sdk}
(Optional, for NativeLink) Populate with a Branch web url that is present on the clipboard on the very first open (if missing, do not include in request)
Valid for ANDROID ONLY (Optional, for Google AdWord Campaigns) Extract the value of gclid from Android PlayStore Install Referrer URL. Utilized for tracking downstream events on Google Adwords when user opts out on Android 12+ devices (if missing, do not include in request)
Valid for IOS ONLY (Optional, for Google AdWord Campaigns) Extract the value of gbraid from the referring url/uri for the app session. Utilized for tracking downstream events on Google Adwords when users are opted out of ATT (if missing, do not include in request)
A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.
A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.
A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.
Whether European regulations, including the DMA, apply to this user and conversion. Required if EU regulations apply to this user.
Whether end user has granted or denied ads personalization consent. Required if dma_eea
is set to true
(i.e., EU regulations apply to this user).
Whether end user has granted or denied consent for 3P transmission of user level data for ads. Required if dma_eea
is set to true
(i.e., EU regulations apply to this user).
Ok
The generated session id assigned against the API Setup. This is the primary response the developer must look into.
The setup data in JSON format set against the API.
Device unique fingerprint identity used for transactional reference.
N/A
Authentication Failed
"{\n \"error\": {\n \"message\": \"Authentication failed !\",\n \"code\": 400\n }\n}"
Rate Limit Reached
"{\n \"error\": {\n \"code\": 429,\n \"message\": \"Rate limit reached.\"\n }\n}"