개발자를 위한 스마트 배너 웹사이트 코드 구현

대상:
개발자
마지막 업데이트:

요약: 마케터가 웹사이트 방문자를 모바일 앱 사용자로 전환할 수 있도록 웹사이트에 스마트 배너 SDK를 추가합니다.

 참고

앱스플라이어 스마트 배너 웹 SDK v1은 2023년 11월 8일부터 더 이상 사용되지 않습니다.웹사이트에 스마트 배너를 표시하려면 v2로 업그레이드해야 합니다.더 알아보기

개요

앱스플라이어는 광고주가 웹사이트에 삽입할 수 있는 스마트 배너 SDK를 제공합니다. SDK는 필요한 데이터를 가져와 스마트 배너에 데이터를 동적으로 표시합니다. 스마트 배너 SDK는 또, 적절한 어트리뷰션 링크를 자동으로 생성해, 링크를 따로 만들 필요가 없습니다.

스마트 배너 SDK는 모바일 배너가 게재되는 모든 페이지에서 접근할 수 있어야 합니다.

스마트 배너 SDK는 웹 사이트 작업 공간에서가져올 수 있는 고유한 웹 키를사용하여 인증합니다.

코드 스니펫

 참고

2020년 1월 1일부터 스마트 배너 SDK를 통해 웹사이트에서 스마트 배너와 사람 기반 어트리뷰션을 모두 사용할 수 있습니다. 아래 SDK 스니펫은 두 가지 예시를 포함합니다.

PBA 용 웹 SDK 를 이미 사용하고 있는 경우 스마트배너와 PBA 둘 다를 사용할 때의 웹 SDK 로 교체하십시오. 단순히 스마트배너 단독 활용 목적의 웹 SDK 를 추가하시면 안 됩니다.

모바일 배너를 게재하는 모든 페이지의 <head> 태그에 코드 스니펫을 삽입합니다.

SDK 스니펫 이전 SDK 스니펫 - 더 이상 사용하지 않음

스마트 배너만을 사용하는 용도의 앱스플라이어 웹 SDK

  1. 스크립트 내 YOUR_WEB_KEY 자리 표시자를 웹 키로 바꿉니다. 웹 키는 웹사이트 작업 공간을 새로 만들 때 생성됩니다.
  2. 이 코드 스니펫을 귀사의 웹사이트 head 태그에 붙여넣습니다. 헤드 태그의 맨 위 가까이에 붙여넣도록 하십시오.
<script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyer.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF","banners",{banners: {key: "YOUR_WEB_KEY"}});

// 스마트 배너는 기본적으로 최대 z-지수 값으로 설정되어 있으므로 웹 사이트 요소에 의해 숨겨지지 않습니다. 일부 웹 사이트 구성 요소를 배너 상단에 표시하려는 경우 변경할 수 있습니다.
          
AF('banners', 'showBanner', { bannerZIndex: 1000, additionalParams: { p1: "v1", p2: "v2"}});

</script>

스마트 배너와 유저 중심 어트리뷰션(PBA)용 앱스플라이어 웹 SDK

  1. 스크립트 내 YOUR_WEB_KEY 자리 표시자를 웹 키로 바꿉니다. 웹 키는 새 웹 사이트 작업 공간을만들 때 만들어집니다.
  2. 스크립트 내 YOUR_PBA_KEY 플레이스 홀더를 귀하의 web dev key로 바꿉니다. web dev key는 브랜드 번들을 생성할 때 만들어집니다.
  3. 이 코드 스니펫을 귀사의 웹사이트 head 태그에 붙여넣습니다. 헤드 태그의 맨 위 가까이에 붙여넣도록 하십시오.
<script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyer.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF", "pba,banners",{pba: {webAppId: "YOUR_PBA_KEY"}, banners: {key: "YOUR_WEB_KEY"}});

// 스마트 배너는 기본적으로 최대 z-지수 값으로 설정되어 있으므로 웹 사이트 요소에 의해 숨겨지지 않습니다. 일부 웹 사이트 구성 요소를 배너 상단에 표시하려는 경우 변경할 수 있습니다.
          
AF('banners', 'showBanner', { bannerZIndex: 1000, additionalParams: { p1: "v1", p2: "v2"}});

</script>

SDK 함수(function)

showBanner

목적: 

스니펫으로 제공된 배너 키에 따라 스마트 배너를 보여주기 시작합니다.

참고: 래퍼/하이브리드 앱에서 앱((브라우저가 아닌)의 배너 페이지를 로드하기 위해 스마트 배너를 구현할 때 이 기능을 사용하지 마십시오. showBanner를 사용하면 배너가 앱 내에 표시됩니다. 래퍼/하이브리드 앱에 showBanner를 사용하는 경우 모바일 앱 로드에는 hideBanner를 사용합니다.

파라미터 (선택 사항):

  • bannerContainerQuery
    이 함수가 전달되면, SDK가 이 쿼리로 페이지 내 요소(element)를 찾으려고 시도하고, 이 요소를 배너 배치를 위한 엔트리 포인트(entry point)로 사용합니다. 혹은 document.body 가 사용됩니다.
  • bannerZIndex
    스마트 배너는 기본적으로 최대 z 색인 값으로 설정되므로 웹 사이트 요소가 숨길 수 없습니다. 이는 일부 웹 사이트 구성요소가 배너의 맨 위에 있도록 하려는 경우에 변경할 수 있습니다.
  • additionalParams
    전달되면, 이 파라미터(예를 들어, deep_link_value)는 쿼리 파라미터로 원링크 URL에 추가됩니다. 

예:

새 SDK 구 SDK - 더 이상 사용하지 않음 
AF('banners', 'showBanner', { bannerContainerQuery: "#container-id",
              bannerZIndex: 1000,              
              additionalParams: { p1: "v1", p2: "v2"...}});

updateParams

목적

배너가 표시된 후에 CTA(call-to-action) 버튼에 지정된 원링크 URL에 프로그램 방식으로 최대 10개의 파라미터(예를 들어, deep_link_value)를 추가합니다. 

입력은 파라미터 키와 값이 있는 객체입니다.

  • 키는 빈 값을 가질 수 없습니다.
  • 키는 undefined, null, NaN, 또는 arg라는 이름을 가질 수 없습니다.
  • 유효하지 않은 문자:
    • Key: /, \, *, !, @, #, ?, $, %, ^, &, ~, `, =, +, ', ", ;, :, >, <
    • Value = \, ;, $, >, <, ^, #, `

예

AF ("banners", "updateParams", {p1: "v1", p2: "v2"...})

고려 사항 

  • 파라미터는 원링크 URL에 쿼리 파라미터로 추가됩니다. 
  • updateParams를 사용하여 파라미터를 추가하는 경우, 노출 URL은 클릭 URL과 다릅니다.
  • 추가된 파라미터는 원래의 원링크 URL의 파라미터를 대체하지 않습니다. 추가하는 파라미터가 이미 원링크 URL에 있다면, 변경되지 않습니다. 
  • updateParams를 두 번 이상 호출하면 마지막 호출의 파라미터만이 URL에 추가됩니다.
  • 이 방법은 더 이상 사용되지 않는 스마트 배너 웹 SDK에서는 작동하지 않습니다.

hideBanner

목적

페이지에서 노출된 배너를 프로그램으로 제거합니다. (예: X초 동안 노출 후 배너 제거)

AF('banners', 'hideBanner')

disableBanners - 더 이상 사용하지 않음

목적

이 함수는 구 스마트 배너 SDK에서만 사용 가능하며 곧 폐기될 예정입니다.

웹 SDK가 배너를 게재하지 않고 앱스플라이어 서버와 통신하지 않도록 설정합니다.

disableTracking - 더 이상 사용하지 않음

목적

이 함수는 구 스마트 배너 SDK에서만 사용 가능하며 곧 폐기될 예정입니다.

웹 SDK를 끄고, 브라우저로부터 수집한 정보(예: 쿠키, 로컬 스토리지 등)의 흔적을 지웁니다.

setAdditionalParams -더 이상 사용하지 않음

목적

이 함수는 구 스마트 배너 SDK에서만 사용 가능하며 곧 폐기될 예정입니다.

showBanner를 호출하기 전에 additionalParams를 원링크에 설정합니다. 이 파라미터들은 배너 뒤 원링크 URL에 추가됩니다.

파라미터

  • 파라미터
    기존 어트리뷰션 링크 파라미터(pid 값 제외)를 덮어쓸 수 있는 키/값 파라미터 맵입니다.

사용법 예시

특정 파라미터를 이용해 랜딩 페이지를 구분할 수 있습니다. 배너 뒤의 원링크에서 추가 파라미터를 추가합니다. 그리고나서 사용자가 배너를 클릭한 후 앱을 설치하면, 원링크의 파라미터가 앱스플라이어 로데이터에 나타납니다. 아래는 af_sub1 parameter를 활용한 코드 예시입니다.

// showBanner()를 호출하기 전에 이 메서드를 호출합니다.
setAdditionalParameters('af_sub': 'custom_paramter_value')

원링크 최종 형식은 다음과 같습니다. subdomain.onelink.me/onelink-id?pid=af_banner&c=campaign&af_sub1=custom_paramter_value

서브 도메인과 원링크 ID는 원링크 템플릿에서 가져옵니다.

For example: ab12.onelink.me/xyz1?pid=af_banner&c=summer_campaign&af_sub1=uk_landing_page.

유용한 파라미터는 모두 사용할 수 있습니다. 어트리뷰션 링크 파라미터에 대한 더 상세한 내용은 여기를 확인하십시오. pid와 c 파라미터를 덮어쓰지 않도록 주의하십시오. 이 파라미터들은 배너 뒤 어트리뷰션 링크에 이미 존재하고 있습니다.

getAdditionalParams- 더 이상 사용하지 않음

목적

이 함수는 구 스마트 배너 SDK에서만 사용 가능하며 곧 폐기될 예정입니다.

현재 additionalParams 객체를 가져옵니다.

특성과 제한 사항

항목 설명
단일 페이지 애플리케이션(SPA)

스마트 배너는 기본적으로 사용자가 페이지 사이를 이동하더라도 한 번만 표시됩니다.

사용자가 페이지 사이를 이동할 때 배너를 표시하려면 페이지를 다시 로드하지 않고 스마트 배너 기본 논리를 트리거하지 않는 모든 탐색에 대해 hideBanner 및 showBanner를 수동으로 호출해야 합니다.

참고 항목