Overview

Branch's Deep Linking API is a powerful tool for all things Branch Links. You can programmatically generate links at scale to support all of your campaigns while tagging the links appropriately based on channel and other analytics tags.

API Limitations

Limitation

Details

사용량 제한

  • 500/second
  • 30,000/minute

Prerequisites & API Access

In order to access the Deep Linking API, you need to have completed the following:

  1. Created a Branch Dashboard

권한인증

Calls to the Deep Linking API require both your Branch Key and (sometimes) Branch Secret parameter to be passed with each request. This can be obtained through the Branch Dashboard Account Settings.

12701270

Learn more about your Branch Account Profile here.

For some calls, you will also need your Branch Access Token. This can be obtained from your Branch Dashboard User Settings.

Learn more on retrieving your Access Token here.

API Usage

Create a Deep Link URL

엔드 포인트

POST /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

Header

필수

Content-Type

application/json

Request Body Parameters:

파라미터

설명

필수

branch_key

The Branch key of the originating app; from your Branch Settings Dashboard

data

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.

아니오

alias

Instead of our standard encoded short url, you can specify the vanity alias. For example, instead of a random string of characters/integers, you can set the vanity alias as .app.link/devonaustin. Aliases are enforced to be unique and immutable per domain, and per link - they cannot be reused unless deleted.

최대 128자

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.

아니오

type

  • URL을 일회용 URL로 만들려면 type을 1로 설정하십시오. 딥링크(Deep Link)를 1회 성공한 후에는 딥링크(Deep Link)를 하지 않습니다.

  • default는 SDK.git를 통해 생성된 표준 Branch 링크인 0으로 설정됩니다.

아니오

duration

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).

아니오

Branch 분석 파라미터

대시보드에서 데이터가 일관되고 읽기 쉽게 표시되도록 조직적인 분석 레이블 구조로 링크에 태그를 지정하는 것이 중요합니다.

아니오

identity

유저를 식별하는 데 사용되는 ID입니다. 링크가 ID에 연결되어 있지 않으면 ID를 지정할 필요가 없습니다.

최대 127자

아니오

Response Body Parameters

파라미터

설명

URL

The deep link URL created by this endpoint.

Example Request/Response

curl -XPOST https://api2.branch.io/v1/url -H "Content-Type: application/json" \
  -d '{
  "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
  "channel": "facebook",
  "feature": "onboarding",
  "campaign": "new product",
  "stage": "new user",
  "tags": ["one", "two", "three"],
  "data": {
    "$canonical_identifier": "content/123",
    "$og_title": "Title from Deep Link",
    "$og_description": "Description from Deep Link",
    "$og_image_url": "http://www.lorempixel.com/400/400/",
    "$desktop_url": "http://www.example.com",
    "custom_boolean": true,
    "custom_integer": 1243,
    "custom_string": "everything",
    "custom_array": [1,2,3,4,5,6],
    "custom_object": { "random": "dictionary" }
  }
}'
{
  "url": "https://example.app.link/WgiqvsepqF"
}

Bulk Create Deep Link URLs

엔드 포인트

POST /v1/url/bulk/{branch_key}
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

For more details on how to create links, see the Branch link creation guide

Request Headers

Header

필수

Content-Type

application/json

Request Body Parameters

A json array of parameters from Creating a Deep Linking URL.

파라미터

설명

필수

branch_key

The Branch key of the originating app; from your Branch Settings Dashboard

Branch 파라미터

A json array of parameters from Creating a Deep Linking URL.
You're free to add any of your own key-value parameters to a Branch link. These parameters will be passed to your app via the Branch SDK.

아니오

📘

Note

There is a 100KB limit on the request payload size.

응답 파라미터

파라미터

설명

url[]

An array of deep linking URLs.

error

error(s) if there are invalid params.

Example Request/Response

curl -XPOST https://api2.branch.io/v1/url/bulk/key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt -H "Content-Type: application/json" \
  -d '[
    {
      "channel": "facebook",
      "feature": "onboarding",
      "campaign": "new product",
      "stage": "new user",
      "tags": ["one", "two", "three"],
      "data": {
        "$canonical_identifier": "content/123",
        "$og_title": "Title from Deep Link",
        "$og_description": "Description from Deep Link",
        "$og_image_url": "http://www.lorempixel.com/400/400/",
        "$desktop_url": "http://www.example.com",
        "custom_boolean": true,
        "custom_integer": 1243,
        "custom_string": "everything",
        "custom_array": [1,2,3,4,5,6],
        "custom_object": { "random": "dictionary" }
      }
    },
    {
      "channel": "facebook",
      "feature": "onboarding",
      "campaign": "new product",
      "stage": "new user",
      "tags": ["one", "two", "three"],
      "data": {
        "$canonical_identifier": "content/123",
        "$og_title": "Title from Deep Link",
        "$og_description": "Description from Deep Link",
        "$og_image_url": "http://www.lorempixel.com/400/400/",
        "$desktop_url": "http://www.example.com"
      }
    }
  ]'
[
  {
    "url": "https://example.app.link/0AjuiLcpqF"
  },
  {
    "url": "https://example.app.link/5IULiLcpqF"
  },
  { 
    'error': 'error message'
  }
]

Delete Existing Deep Link

엔드 포인트

DELETE /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

📘

테스트 환경에서 사용할 수 없음

Request Headers

Header

필수

Content-Type

application/json

Request Body Parameters

파라미터

설명

필수

access_key

Your API Key / Access Token; Learn how to retrieve your API key (a.k.a. Access Token)

URL

The Deep Link URL to be deleted

응답 파라미터

파라미터

설명

URL

The Deep Link URL to be deleted

deleted

Returns true if the URL has been successfully deleted, false if not.

Example Request/Response

curl -X DELETE \
'https://api2.branch.io/v1/url?url=https://example.app.link/ABCD&app_id=YOUR_APP_ID' \
  -H "Access-Token: YOUR_ACCESS_TOKEN"
{
  "url": "https://example.app.link/ABCD",
  "deleted": true
}

Read Existing Deep Link

엔드 포인트

GET /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

Header

필수

Content-Type

application/json

Request Body Parameters:

파라미터

설명

필수

branch_key

The Branch key of the originating app; from your Branch Settings Dashboard

URL

읽게 할 딥링크(Deep Link) URL.

응답 파라미터

파라미터

설명

array of properties

Returns Android SDK deep link properties](/ko/using-branch/docs/creating-a-deep-link#section-read-deep-links).

Example Request/Response

curl -XGET 'https://api2.branch.io/v1/url?url=https://example.app.link/WgiqvsepqF&branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt'
{
  "campaign": "new product",
  "channel": "facebook",
  "feature": "onboarding",
  "stage": "new user",
  "tags": [
    "one",
    "two",
    "three"
  ],
  "data": {
    "$canonical_identifier": "content/123",
    "$desktop_url": "http://www.example.com",
    "$og_description": "Description from Deep Link",
    "$og_image_url": "http://www.lorempixel.com/400/400/",
    "$og_title": "Title from Deep Link",
    "$one_time_use": false,
    "custom_array": [
      1,
      2,
      3,
      4,
      5,
      6
    ],
    "custom_boolean": true,
    "custom_integer": 1243,
    "custom_object": {
      "random": "dictionary"
    },
    "custom_string": "everything",
    "~campaign": "new product",
    "~channel": "facebook",
    "~creation_source": 0,
    "~feature": "onboarding",
    "~id": "423196192848102356",
    "~stage": "new user",
    "~tags": [
      "one",
      "two",
      "three"
    ],
    "url": "https://example.app.link/WgiqvsepqF"
  },
  "type": 0,
  "alias": null
}

Update Existing Deep Link

엔드 포인트

PUT /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

Header

필수

Content-Type

application/json

Request Body Parameters:

파라미터

설명

필수

branch_key

The Branch key of the originating app; from your Branch Settings Dashboard

branch_secret

The Branch secret if the originating app; from your Branch Settings Dashboard

URL

The deep link url you want updated

Example Request/Response

curl -XPUT 'https://api2.branch.io/v1/url?url=https%3A%2F%2Fexample.app.link%2F5IULiLcpqF' -H "Content-Type: application/json" \
  -d '{
  "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
  "branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
  "channel": "twitter",
  "data":{
    "name":"alex",
    "user_id":"12346"
  }
}'
{
  "data": {
    "+url": "https://example.app.link/5IULiLcpqF",
    "~creation_source": 0,
    "user_id": "12346",
    "$one_time_use": false,
    "~id": "423196096467215333",
    "name": "alex",
    "~campaign": "new product",
    "~channel": "twitter",
    "$identity_id": "755468067194863158",
    "~stage": "new user",
    "~feature": "onboarding",
    "url": "https://example.app.link/5IULiLcpqF"
  },
  "type": 0,
  "campaign": "new product",
  "feature": "onboarding",
  "channel": "twitter",
  "stage": "new user"
}

링크 업데이트 팁

  • Link 업데이트 API가 링크의 데이터 객체를 완전히 겹쳐 쓰므로 업데이트할 때 (변경하는 데이터뿐 아니라) 링크의 모든 데이터를 포함해야 합니다.
  • To update links in bulk, combine the Link update and Link read APIs when creating a script.

The sample Python script below reads a 2-column CSV file, and updates a key specified in the script for all links listed in column A, with the values in column B:

import requests
import csv
import sys
import urllib
import json

def BranchUpdateModule(KeyV, SecretV, UpdateV, File):
    #Insert API key & App Secret from the Branch dashboard, and the Link data key you want to change in each link **
    branch_key = KeyV
    branch_secret = SecretV
    key_to_update = UpdateV


    #Insert filename for CSV containing links to update in first column, and values to add in second column **
    ifile = open(File, "r", encoding="utf-8")

    #Constants
    branchendpoint = "https://api2.branch.io/v1/url?url="
    reader = csv.reader(ifile, delimiter=',')


    # Uncomment the next line if you want the script to skip the first line of the CSV
    next(reader)

    # Loop through CSV
    for row in reader:

        # Retrieve link data for link being updated
        url = urllib.parse.quote_plus(row[0])
        getrequest = branchendpoint + url + "&branch_key=" + branch_key
        linkdata = requests.get(getrequest)
        jsonData = json.loads(linkdata.text)

        if linkdata.status_code != 200:
            print('Failed: {}'.format( getrequest))
            continue

        # Set credentials for update API
        jsonData["branch_key"] = branch_key
        jsonData["branch_secret"] = branch_secret

        #TODO for editing new value
        newValue = row[1]
        if key_to_update in jsonData:
            jsonData[key_to_update] = newValue
        if key_to_update in jsonData["data"]:
            jsonData["data"][key_to_update] = newValue

        if jsonData.get('type', None) is not None:
            del jsonData['type']
        if jsonData.get('alias', None):
            del jsonData['alias']
        payload = json.dumps(jsonData)
        #print("\n \n payload")
        #print(payload)
        putrequest = branchendpoint + url

        print(putrequest)
        r = requests.put(putrequest, json=jsonData)
        #print("\n \n")
        print(r.url)
        print(r)

        # print

    ifile.close()

Link Update Restrictions

링크 업데이트를 시도할 때 다음과 같은 제한 사항이 있습니다.

  • Not all links are updateable, namely links with the structure of bnc.lt/c/ or bnc.lt/d/
  • The alias of a link cannot be updated, e.g. 'https://bnc.lt/test' -> 'https://bnc.lt/test1'
  • Branch 링크와 관련된 ID를 업데이트할 수 없습니다.
  • 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
  • 다음 추가 필드는 업데이트할 수 없습니다.
    • app_id
    • randomized_bundle_token
    • domain
    • state
    • creation_source
    • app_short_identifier