원링크 API

프리미엄

요약: 원링크(OneLink) API는 SMS 문자 메시지 등 여러 경로를 통해 대규모 캠페인에서 개인화된 링크를 생성하여 최종 사용자의 참여를 유도하고 온드 미디어(owned media) 활용도를 높입니다. 광고주와 개발사가 같이 구현해야 합니다.

원링크 API

원링크 API는 다음과 같이 사용됩니다.

  • 커스텀 파라미터를 사용해 원링크 숏 URL을 자동으로 생성호출업데이트삭제합니다.
    파라미터 종류:
    • 미디어소스, 캠페인, 광고 세트 같은 마케팅 성과 측정 및 모니터링에 사용되는 어트리뷰션 관련 파라미터 일러두기: 미디어 소스(pid) 파라미터는 필수입니다.  
    • 관련 링크에서 앱을 여는 경우 사용자정의 사용자 경험을 설정할 수 있도록 개인화된 파라미터. 파라미터로 사용자정의 인앱 콘텐츠를 사용자에게 보낼 수 있습니다(예: 특정 제품 페이지, 쿠폰 코드, 프로모션).
  • 모바일 사용자에게 웹사이트 및 앱 콘텐츠를 직접 공유할 수 있습니다(이를 통해 모바일 인게이지먼트 및 인스톨이 증가함).
  • 원링크 어트리뷰션 커스텀 링크를 대량으로 즉시 생성합니다.
    일러두기: 추천 링크에 대해서는 사용자 초대 어트리뷰션 문서를 참조하세요.

 예시

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

사용자의 원링크 API 쿼리 수는 계정 유형에 따라 제한됩니다. 원링크 API 대시보드에서 생성한 쿼리 수와 남아 있는 쿼리 수를 확인할 수 있습니다. 

고객 성공 매니저에 문의하여 API 쿼리 제한을 늘릴 수 있습니다.  

설정

원링크 API 설정하기:

  1. 원링크 템플릿을 생성하세요.
  2. 원링크 ID를 입력하세요.  

  3. 원링크 API 키를 입력합니다. 어드민 사용자가 API 키를 가져와야 하며 계정 사용자는 접근 권한이 없습니다. 
    • 앱스플라이어의 사이드 메뉴에서 Engage > 원링크 API > 원링크 API 키 보기 를 선택합니다.
    • 원링크 API 키가 관리자 사용자용이 아니라면 필요한 패키지를 가지고 있지 않다는 의미이며, CMS로 문의해야 합니다.
  4. 원링크 ID와 원링크 API 키를 개발사에 제공합니다.
  5. 개발사가 개발 허브 지침을 따르도록 하세요.

대시보드

원링크 API 대시보드에는 다음 사항이 표시됩니다.

  • 일별, 월별 및 3개월 API 사용량
  • 원링크 API 키

원링크 API 대시보드를 보는 방법

앱스플라이어 플랫폼의 사이드 메뉴에서 Engage > OneLink API를 선택합니다.

특징 및 제약사항

특징

설명

API 할당량 한도

  • 원링크 API를 사용하여 원링크 링크를 생성, 편집 또는 삭제하는 한도는 계정당 월(UTC 시간대) 750만 개입니다.
  • 이 한도를 초과한 후 발생하는 요청은 처리되지 않으며 링크가 생성되지 않습니다. 한도 초과 후 API를 호출할 경우, 오류 상태 코드 429와 함께 “월 한도 초과"라는 메시지를 수신합니다.
  • 사용량/잔여량 정보는 원링크 API 대시보드에 표시됩니다. 

기준 시간 내 API 호출 최대 횟수

  • 기준 시간 내 API 최대 호출 횟수는 초당 500회(분당 30000회)입니다.
  • 초당 500건의 호출(분당 30000건)을 초과하는 모든 호출은 처리되지 않으며 링크가 생성되지 않습니다. 기준 시간 내 최대 호출 횟수를 초과한 뒤의 API 호출을 할 경우, "Rate limit exceeded"라는 메시지와 함께 오류 상태 코드 429를 수신하게 됩니다.

링크 조회

  • API를 통해 작성된 링크는 앱스플라이어 대시보드의 원링크 커스텀 링크 목록에 나타나지 않습니다.
  • 권장 사항: API로 생성한 링크를 로컬에 표로 저장하여 향후 필요시 사용하세요. 

TTL (time-to-live: 유효 기간)

  • 원링크 API로 생성된 원링크 단축 URL의 기본 유효 기간(TTL)은 31일입니다. 링크를 클릭할 때마다 60일씩 늘어납니다. TTL이 만료된 링크를 클릭해도 원링크 기본 구성에서 정의된대로 작동되지만 어트리뷰션으로 집계되지는 않습니다.
    • TTL이 만료된 후 원링크의 단축 URL이 삭제되는 데 최대 48시간이 걸릴 수 있습니다.
  • 최대 TTL은 31일입니다. 31일을 초과하는 모든 TTL 값은 기본 TTL인 31일로 대체됩니다.
  • 파라미터 ttl={value} 를 추가하여 일, 시간 또는 분 단위로 지정할 수 있습니다. 예를 들어 ttl=7d, ttl=12h, 혹은  ttl=10m로 설정 가능합니다.
  • TTL을 정의하시려면 업데이트 요청을 보내세요. 업데이트 요청을 하시면 (기존 링크에 대한) TTL이 요청서 본문에 정의된대로 재설정됩니다.
    • 이것은 TTL이 대체된다는 것을 의미합니다. 예를 들어 현재 TTL이 29일인 링크를 TTL 2일로 업데이트를 요청하면 TTL = 2d(TTL = 31d가 아님)로 변경됩니다.
    • TTL 업데이트 요청으로 어트리뷰션 링크의 수명을 연장할 수 있습니다. 예를 들어, 현재 잔여 유효 기간이 20일 남은 링크에 대해 TTL을 31일로 업데이트하도록 요청했으나 5일이 경과되면 TTL은 업데이트 시점에 31일이 됩니다.
  • 링크 TTL이 자동으로 확장되지 않도록 하려면 링크에 파라미터 renew_ttl=false 를 추가하세요. 이 파라미터의 값은 true (기본값) 또는 false인 boolean 데이터 유형입니다.
  • 파라미터 renew_ttl 는 실제 URL에 표시되지 않습니다.

특수 문자

특수 문자를 API 생성 링크에 사용하는 경우 다음 문자를 인코딩해야 합니다. ;, *, !, @, #, ?, $, ^, :, &, ~, `, =, +, ', >, <, /
이러한 문자를 인코딩하지 않으면 공백으로 바뀌고 링크와 해당 기능이 중단될 수 있습니다.

페이로드

페이로드의 쿼리 문자열은 2,048자를 초과할 수 없습니다.

URL ID

URL ID(또는 숏링크 ID)를 편집하여 캠페인 콘텐츠를 강조할 수 있습니다. 예: https://myapp.onelink.me/abc123/apples URL ID는 50자를 초과할 수 없으며 문자와 숫자를 조합할 수 있습니다. 기본적으로 8자입니다.

일러두기:

  • 현재 ID가 사용되고 있지 않은 경우에만 URL ID를 편집할 수 있습니다.
  • URL ID가 이미 사용 중이면 링크를 생성할 수 없고, 오류 응답(400)이 반환됩니다. 앱 소유주와 개발자는 이러한 이벤트가 발생할 경우 어떻게 처리할지 정의하고 구현해야 합니다.
  • 실패한 호출도 월간 API 할당량 소진으로 반영됩니다.