OneLink API

요약: OneLink REST API를 통해, 원링크 어트리뷰션 링크를 생성, 업데이트, 회수 및 삭제할 수 있습니다.

OneLink API is used to:

  • Create, get, update, and delete OneLink URLs automatically.
  • Generate a large number of OneLink custom attribution links.
  • Customize OneLink URLs with your brand. This means that when you generate the URL, it has your brand domain, instead of the OneLink subdomain.

 

식품 배달 기업, Feed Me에서 기존 회원 고객에게 SMS 문자메시지로 개인화된 링크를 전송하여 Feed Me 앱을 다운로드 받고 바나나를 구매하도록 마케팅을 하려고 합니다. Feed Me는 원링크 REST API를 사용해 고객의 국가에 관련된 특정 콘텐츠와 (고객이 로그인한 경우) 유저 ID, 바나나 세일 정보를 포함한 커스텀 원링크 URL을 생성할 수 있습니다.

OneLink API

인증 키 

원링크 API 요청은 반드시 OneLink API Key를 사용해 인증되어야 합니다. 

선행 조건:

  • 계정 관리자가 API 키를 확인해야 합니다. 팀 멤버는 API 키에 접근 권한이 없습니다. 

원링크 API 키를 확인하려면:

  • Go to Integration > API Access, scroll down to the OneLink API section. OL_API_key.png
  • API 호출은 https 에서 수행해야 합니다.
  • API 횟수 제한: API를 통해 원링크 어트리뷰션 링크를 생성하는 횟수 제한은 일 별, 계정 별 250,000회 입니다.
  • 필요사항: onAppOpenAttribution을 통한 리타겟팅 어트리뷰션 데이터는 앱스플라이어 SDK, iOS 및 안드로이드 모두, 버전 4.8.0 및 그 이상에서 가능합니다. 

제한 사항

원링크 API는 다음 제한 사항이 있습니다.

  • 이 API를 통해 작성된 링크는 앱스플라이어 대시보드의 원링크 커스텀 링크 목록에 나타나지 않습니다.
  • API에 의해 생성된 각 원링크 어트리뷰션 링크는 31일의 기본 Time to Live(TTL) 기간을 가집니다. 31일이 지나면, 해당 어트리뷰션 링크 기록은 시스템에서 삭제됩니다. TTL이 만료된 이후, 이 어트리뷰션 링크를 클릭하면, 원링크 기본 설정에 정의된 행동대로 디폴트 됩니다. 최대 TTL은 31일 입니다.
  • 31일을 초과하는 모든 TTL은 기본 TTL인 31일로 대체됩니다.
  • TTL 값은 일자 (기본 값) 또는 분, 시간으로 지정될 수 있습니다. (예, 10m, 20h, 14d)
  • 원링크 API 데이터 페이로드에서 특수문자 "&"을 사용할 수 없습니다.

 참고

  • 원링크 API를 통해 생성한 링크에만 원링크 API를 사용합니다.
  • 링크 관리 페이지에서 생성되어 단축된 원링크 URL을 업데이트 하거나 삭제하는데 원링크 API를 사용하지 마십시오. 이는 운영중인 URL을 중단시킬 수 있습니다.

용어 사전

Onelink ID
원링크 ID는 원링크 템플릿 화면에 설정된, 원링크에 대한 고유 식별자입니다.
Shortlink ID
주어진 원링크 API 생성 어트리뷰션 링크: myapp.onelink.me/ab12/qwer987 - 숏링크 ID는 어트리뷰션 링크 구조의 마지막 요소입니다. 위의 예시에서 숏링크 ID는 qwer987 입니다.

원링크 어트리뷰션 링크 생성하기

원링크 ID와 쿼리 파라미터 세트가 주어졌을 때, 이 API는 단축된 원링크 어트리뷰션 링크를 리턴합니다.

파라미터 설명

URL

https://onelink.appsflyer.com/shortlink/v1/:onelink-id

방법

POST

URL 파라미터

필수:

onelink-id=[alphaNumeric]

원링크 템플릿 화면에서 확인.

데이터 파라미터

  • 브랜드 링크 (앱스플라이어 프리미엄 기능) 원링크 도메인 대신 사용자의 브랜드 도메인을 사용하십시오. 
  • [선택 사항] brand_domain: 이 파라미터는 다음의 경우에만 사용하고 페이로드(payload)에서 요청하십시오.
    • 브랜드 링크 기능이 계정에서 활성화되어야 합니다.
    • The branded link is configured in your account.
      Click here to learn how to enable the feature and to configure a branded link.
      Important: If the above conditions are not met, do not use this param, as the API call will not work.
  • TTL (선택적): 전체 어트리뷰션 링크에 대한 사용 시간(Time to Live).
  • 데이터: 어트리뷰션 링크의 앱스플라이어 매크로 다음에 있는 JSON 형식의 쿼리 파라미터.
예:
{
 "brand_domain": "click.example.com", #optional, requires a configured branded link
 "ttl" : "25", #optional, default is 31d
 "data" :
   {
   "pid" : "SMS-Offer",
   "c" : "April-Coupon",
   "Custom_param" : "value"
   }
}

성공 응답

성공적인 응답은 단축 원링크 어트리뷰션 링크 URL (숏링크)나 원링크와 숏링크 ID를 가진 브랜드 링크를 포함합니다. 브랜드 링크를 지정했는데 설정되지 않았다면, 응답은 숏링크를 포함합니다.

예:

Code: 200

  • 숏링크: https://myapp.onelink.me/abc123/qwer9876
  • 브랜드 링크: https://click.example.com/abc123/qwer9876

오류 응답

오류 코드 콘텐츠 참고
401 UNAUTHORIZED { error : "Authentication Failed" }  
400 API limit reached { error : "Data sent exceeds limit" }  

샘플 호출

curl -X POST \
 https://onelink.appsflyer.com/shortlink/v1/abc123 \
 -H 'authorization: [Your OneLink API Key]'\
 -H 'content-type: application/json' \
 -d '{"brand_domain": "click.example.com"
 "ttl" : "25",
   "data" : {
   "pid": "your PID here",
   "c": "your campaign here"
   }
 }'

참고

앱스플라이어는 어떤 링크를 생성하더라도 pid 파라미터 (미디어 소스 이름)를 포함하도록 권장합니다. 만약 API 호출에 pid 파라미터가 제공되지 않았다면, 모든 관련 인스톨은 앱스플라이어 대시보드와 리포트에서 "None" 미디어 소스로 어트리뷰션 됩니다.

원링크 어트리뷰션 링크 업데이트 하기

원링크 ID, 숏링크 ID와 쿼리 파라미터 세트가 주어졌을 때, 이 API는 주어진 어트리뷰션 링크를 제공된 쿼리 파라미터로 업데이트합니다.

파라미터 설명

URL

https://onelink.appsflyer.com/shortlink/v1/:onelink-id?id=:shortlink-id

방법

데이터를

URL 파라미터

필수:

onelink-id=[alphaNumeric]

원링크 템플릿 화면에서 확인.

shortlink-id=[alphaNumeric]

단축된 원링크 쿼리 파라미터의 ID 입니다. 예: 다음 원링크 어트리뷰션 링크 myapp.onelink.me/abc123/qwer9876 에서, 숏링크 ID(단축된 원링크의 ID)는 qwer9876 입니다.

데이터 파라미터

  • brand_domain (선택적): request payload에 브랜드 링크를 지정할 수 있지만 두가지 필수 조건이 있습니다.
    • 브랜드 링크 기능이 계정에서 활성화되어야 합니다.
    • 브랜드 링크는 계정에서 설정됩니다.
      여기를 클릭하여 어떻게 브랜드 링크 기능을 활성화하고 설정하는지 참조하십시오.
  • TTL (선택적): 전체 어트리뷰션 링크에 대한 사용 시간(Time to Live). 최대 및 기본 TTL 값은 31일 입니다. 31일을 초과하는 모든 TTL은 기본 TTL인 31일로 대체됩니다. 이 기간은 분, 시간 또는 일 단위 (10m/10h/10d)로 지정될 수 있으며, 아무 지정이 없다면 기본 설정은 일 별 단위입니다.
  • 데이터: 어트리뷰션 링크의 앱스플라이어 매크로 다음에 있는 JSON 형식의 쿼리 파라미터.

예:

{
 "brand_domain": "click.example.com", #optional, requires a configured branded link
 "ttl" : "25", #optional, default is 31d
 "data" :
   {
   "pid" : "SMS-Offer",
   "c" : "April-Coupon",
   "custom_param" : "value"
   }
}

성공 응답

성공적인 응답은 단축 원링크 어트리뷰션 링크 URL (숏링크)나 원링크와 숏링크 ID를 가진 브랜드 링크를 포함합니다. 브랜드 링크를 지정했는데 설정되지 않았다면, 응답은 숏링크를 포함합니다.

예:

Code: 200

  • 숏링크: https://myapp.onelink.me/abc123/qwer9876
  • 브랜드 링크: https://click.example.com/abc123/qwer9876

오류 응답

Code: 401 UNAUTHORIZED

Content: { error : "Authentication Failed" }

혹은

Code: 400 Data Error

Content: { error : "Invalid/no data in request" }

혹은

Code: 400 API limit reached

Content: { error : "Data sent exceeds limit" }

샘플 호출

curl -X PUT\
https://onelink.appsflyer.com/shortlink/v1/abc123?id=qwer9876 \
 -H 'authorization: [Your OneLink API Key]'\
 -H 'content-type: application/json' \
 -d '{"brand_domain": "click.example.com"
   "ttl" : "25",
   "data" : {
   "pid" : "your PID here",
   "c" : "your campaign here"
      }
   }'

원링크 어트리뷰션 링크 가져오기

원링크 ID, 숏링크 와 숏링크 ID가 주어지면, 이 API는 이 어트리뷰션 링크에 정의된 쿼리 파라미터를 리턴합니다.

파라미터 설명

URL

https://onelink.appsflyer.com/shortlink/v1/:onelink-id?id=:shortlink-id

방법

GET

URL 파라미터

필수:

onelink-id=[alphaNumeric]

원링크 템플릿 화면에서 확인.

shortlink-id=[alphaNumeric]

단축된 원링크 쿼리 파라미터의 ID 입니다. 예: 다음 원링크 어트리뷰션 링크 myapp.onelink.me/abc123/qwer9876 에서, 숏링크 ID(단축된 원링크의 ID)는 qwer9876 입니다.

데이터 파라미터

없음

성공 응답

성공적인 응답은 숏링크를 정의하는데 사용된 쿼리 파라미터의 JSON을 포함합니다.

예:

Code: 200

콘텐츠:

{ "pid": "sms-offer"
"c": "april-coupon"
}

오류 응답

Code: 401 UNAUTHORIZED

Content: { error : "Authentication Failed" }

혹은

Code: 404 Shortlink record not found

Content: { error : "Record Not Found" }

샘플 호출

curl -X GET \
"https://onelink.appsflyer.com/shortlink/v1/abc123?id=qwer9876 \
-H 'authorization: [Your OneLink API Key]'\
-H 'content-type: application/json'

원링크 어트리뷰션 링크 삭제하기

원링크 ID와 숏링크 ID가 주어지면, 이 API는 해당 어트리뷰션 링크를 삭제하고 무효화합니다. 이 어트리뷰션 링크의 모든 후속 클릭은 원링크 설정의 기본 정의로 디폴트 합니다.

파라미터 설명

URL

https://onelink.appsflyer.com/shortlink/v1/:onelink-id?id=:shortlink-id

방법

DELETE

URL 파라미터

필수:

onelink-id=[alphaNumeric]

원링크 템플릿 화면에서 확인.

shortlink-id=[alphaNumeric]

단축된 원링크 쿼리 파라미터의 ID 입니다. 예: 다음 원링크 어트리뷰션 링크 myapp.onelink.me/abc123/qwer9876 에서, 숏링크 ID(단축된 원링크의 ID)는 qwer9876 입니다.

데이터 파라미터

없음

성공 응답

예:

Code: 200

콘텐츠: ok

오류 응답

Code: 401 UNAUTHORIZED

Content: { error : "Authentication Failed" }

혹은

Code: 404 Shortlink record not found

Content: { error : "Record Not Found" }

샘플 호출

curl -X DELETE \
"onelink.appsflyer.com/shortlink/v1/abc123?id=qwer9876 \
-H 'authorization: [Your OneLink API Key]'\
-H 'content-type: application/json'

자주 하는 질문

다음의 자주 하는 질문을 참고하여 원링크 API 사용 관련 더 자세히 알아보십시오.

API를 사용하여 생성한 모든 원링크 목록을 얻을 수 있습니까?

현재 API를 사용하여 생성한 모든 원링크를 나열하는 API는 없습니다.

어떻게 원링크 TTL을 확인할 수 있습니까?

원링크가 생성될 때 TTL이 지정되지 않은 경우, 기본 값은 31 일 입니다. 원링크를 호출할 때 TTL 값을 얻는 것은 불가능합니다.  

TTL을 연장할 수 있습니까?

네, 업데이트 요청을 전송하여 TTL을 지정합니다. 모든 업데이터 요청은 요청 본문에 지정된대로 TTL을 재설정합니다.

원링크를 생성할 때 숏링크 ID를 설정할 수 있습니까?

원링크를 생성할 때 숏링크 ID를 선택하거나 설정하는 것은 불가능합니다.

도움이 되었습니까?