• 개발자 가이드
  • SDK Integration
  • Web SDK

Web SDK

Web SDK 설치하기

에어브릿지 Web SDK는 아래 방법으로 패키지를 설치할 수 있습니다.

지원 브라우저

에어브릿지 Web SDK는 ES5를 지원하는 모든 브라우저에서 동작합니다.

SDK 초기화하기

에어브릿지 Web SDK는 airbridge.init() 함수를 사용하여 초기화할 수 있습니다. 초기화 시 필수로 입력해야 하는 app과 webToken은 에어브릿지 대시보드의 설정 → 토큰 관리에서 확인할 수 있습니다. 필요에 따라 다양한 초기화 옵션을 추가로 설정할 수 있습니다.

아래는 초기화에 필요한 설정의 타입입니다.

JavaScript
interface InitializeOptions { app: string webToken: string autoStartTrackingEnabled?: boolean utmParsing?: boolean utmParameterValueReplaceMap?: Record<string, Record<string, string>> urlQueryMapping?: Record<string, string> userHash?: boolean cookieWindow?: number cookieWindowInMinutes?: number useProtectedAttributionWindow?: boolean protectedAttributionWindowInMinutes?: number shareCookieSubdomain?: boolean collectMolocoCookieID?: boolean}

설치 확인하기

에어브릿지 Web SDK를 설치한 페이지로 이동하여 개발자 도구를 열고 다음 코드를 실행합니다.

console.log(airbridge.isSDKEnabled)

위 코드를 입력하고 실행했을 때 true 가 출력된다면 정상적으로 설치되고 초기화된 것입니다.

주의하세요

airbridge.isSDKEnabled 는 최초에 false 입니다. Web SDK가 모두 로드되고 초기화가 성공적으로 완료되면 true 로 변경됩니다.

네트워크 환경에 따라 로드가 지연될 수 있으며, 로드가 완료되기 전에 확인하면 false 가 출력될 수 있습니다.

네트워크 지연으로 인한 false 출력이 의심되는 경우, 개발자 도구에서 아래 코드를 실행하여 5초 후에 값을 확인하세요.

setTimeout(function () { console.log(airbridge.isSDKEnabled)}, 5000)

옵트인(Opt-In) 설정하기

알립니다

필수 설정 기능이 아닙니다. 필요한 기능인지 확인한 후에 설정하세요.

옵트인(Opt-In)은 유저가 동의할 때에만 유저 정보를 사용하는 정책입니다.

autoStartTrackingEnabled 옵션을 false로 설정한 후에, 이벤트를 수집할 수 있는 시점에 startTracking 함수를 호출하세요. startTracking 함수가 호출된 시점부터 이벤트 수집을 시작합니다.
기본 설정은 true입니다.

  1. autoStartTrackingEnabled 설정으로, 초기화를 마친 후에 자동으로 이벤트 추적이 시작되지 않도록 설정하세요.

    airbridge.init({ app: 'YOUR_APP_NAME', webToken: 'YOUR_WEB_TOKEN', // ... autoStartTrackingEnabled: false,})

  2. 개인정보 수집 및 활용에 대한 유저 응답을 수집하세요. 유저가 개인정보 수집 및 활용에 동의하면 이벤트 추적을 시작합니다.

    airbridge.startTracking()

옵트아웃(Opt-Out) 설정하기

알립니다

필수 설정 기능이 아닙니다. 필요한 기능인지 확인한 후에 설정하세요.

옵트아웃(Opt-Out)은 유저가 거부하기 전까지 유저 정보를 사용할 수 있는 정책입니다.

autoStartTrackingEnabled 옵션을 true로 설정한 후에, 이벤트를 수집할 수 없는 시점에 stopTracking 함수를 호출하세요. stopTracking 함수가 호출된 시점부터 이벤트 수집을 시작합니다.

  1. autoStartTrackingEnabled 설정으로, 초기화를 마친 후에 자동으로 이벤트 추적이 시작되도록 설정하세요. autoStartTrackingEnabled 옵션의 기본값이 true이기 때문에 입력하지 않아도 자동으로 이벤트를 추적합니다.

    airbridge.init({ app: 'YOUR_APP_NAME', webToken: 'YOUR_WEB_TOKEN', // ... autoStartTrackingEnabled: true,})

  2. 개인정보 수집 및 활용에 대한 유저 응답을 수집하세요. 유저가 개인정보 수집 및 활용을 거부하면 이벤트 추적을 중단합니다.

    airbridge.stopTracking()

웹 이벤트

에어브릿지 SDK가 서비스에서 발생한 유저의 특정 행동을 설정에 따라 수집한 후에 이벤트로 전송합니다.

웹 이벤트 전송하기

웹 이벤트를 전송하기 위해 airbridge.events.send 함수를 사용합니다.
아래 예시를 참고하세요.

airbridge.events.send('category', { label: 'Tool', action: 'Hammer', value: 10, semanticAttributes: { currency: 'USD', transactionID: 'transaction_123', products: [ { productID: 'coke_zero', name: 'PlasticHammer', }, ], }, customAttributes: { promotion: 'FirstPurchasePromotion', },})

각 구성요소의 정의와 사용할 수 있는 문자열을 아래에서 확인하세요.

웹 이벤트 추가 설정하기

알립니다

필수 설정 기능이 아닙니다. 필요한 기능인지 확인한 후에 설정하세요.

전송하는 웹 이벤트에 필요한 설정을 추가할 수 있습니다.

이벤트 예시 코드

에어브릿지가 수집하는 주요 인앱 이벤트는 스탠다드 이벤트와 커스텀 이벤트입니다. 스탠다드 이벤트는 에어브릿지가 정의한 이벤트입니다. 아래 예시 코드를 참고하세요.

커스텀 이벤트는 앱 서비스에 맞는 광고 성과를 추적하기 위해 스탠다드 이벤트에 해당하지 않는 유저의 행동을 새로 정의한 이벤트입니다. 아래 예시 코드를 참고하세요.

airbridge.events.send('category', { label: 'Tool', action: 'Hammer', value: 10, semanticAttributes: { currency: 'USD', transactionID: 'transaction_123', products: [ { productID: 'coke_zero', name: 'PlasticHammer', }, ], }, customAttributes: { promotion: 'FirstPurchasePromotion', },})

유저 정보

유저 정보를 설정하세요.

유저 ID 설정하기

유저 ID는 서비스에서 활용하는 유저 식별자입니다. 유저 ID는 유저를 웹과 앱에서 하나의 유저로 특정할 수 있는 고유한 ID이어야 합니다. 설정한 유저 정보는 브라우저의 Local Storage에 남아 유저 정보를 초기화하기 전까지 모든 이벤트에 함께 전송됩니다.

아래 예시를 참고하세요.

// IDairbridge.setUserID('testID')airbridge.clearUserID() // aliasairbridge.setUserAlias('ADD_YOUR_KEY', 'value')airbridge.removeUserAlias('DELETE_THIS_KEY')airbridge.clearUserAlias()

유저 속성 설정하기

주의하세요

민감한 유저 정보가 포함될 수 있습니다. 법률 자문사와 충분히 검토한 후에 전송하세요.

유저 속성을 설정하면 추가 유저 정보를 전송할 수 있습니다.

// Automatically hashed on client side using SHA256// Can turn off hashing feature with special flagairbridge.setUserEmail('testID@ab180.co')airbridge.setUserPhone('821012341234') // attributesairbridge.setUserAttribute('ADD_YOUR_KEY', 1)airbridge.setUserAttribute('ADD_YOUR_KEY', 1.0)airbridge.setUserAttribute('ADD_YOUR_KEY', '1')airbridge.setUserAttribute('ADD_YOUR_KEY', true)airbridge.removeUserAttribute('DELETE_THIS_KEY')airbridge.clearUserAttributes()

유저 이메일과 전화번호를 해시화하여 전송할 수 있습니다. 기본 설정은 true입니다. 유저 ID는 해시 옵션 적용을 받지 않으므로, 해시화가 필요한 경우에는 직접 유저 ID를 해시화하여 값을 넣어주세요.

airbridge.init({ app: '<YOUR_APP_NAME>', webToken: '<YOUR_WEB_TOKEN?', // ... userHash: false, // Default true})

유저 정보 초기화하기

clearUser 함수로 유저 정보를 초기화할 수 있습니다.

airbridge.clearUser()

웹투앱 설정

openDeeplink 함수를 웹 페이지에 있는 버튼에 적용해 유저를 앱으로 보낼 수 있습니다. 아래처럼 주로 버튼에 사용할 수 있습니다. 예시 코드 안의 <BUTTON_ID>에는 실제로 유저가 클릭하는 버튼의 ID를 입력하세요.

<button id="<BUTTON_ID>">앱으로 보기</button><script> document.querySelector('#<BUTTON_ID>').addEventListener('click', () => { airbridge.openDeeplink({ ... }) })</script>

openDeeplink 함수에 대한 예시 코드입니다.

airbridge.openDeeplink({ deeplinks: { // Please use the custom scheme URL like `<YOUR_SCHEME>://...` // Don't use the `intent://...`, `market://...` or `https://...` android: '<YOUR_SCHEME>://path?key=value', // Please use the custom scheme URL like `<YOUR_SCHEME>://...` // Don't use the `intent://...`, `market://...` or `https://...` ios: '<YOUR_SCHEME>://path?key=value', desktop: 'https://www.example.com/path?key=value', }, fallbacks: { // Please use `google-play` or website URL like `https://www.example.com/...`. // Don't use the store URL like `https://play.google.com/...` android: 'google-play', // Please use `itunes-appstore` or website URL like `https://www.example.com/...`. // Don't use the store URL like `https://apps.apple.com/...` ios: 'itunes-appstore', }, ctaParams: { cta_param_1: '<EXAMPLE_CTA_PARAM_1>', cta_param_2: '<EXAMPLE_CTA_PARAM_2>', cta_param_3: '<EXAMPLE_CTA_PARAM_3>', }, defaultParams: { campaign: '<EXAMPLE_CAMPAIGN>', medium: '<EXAMPLE_MEDIUM>', term: '<EXAMPLE_TERM>', content: '<EXAMPLE_CONTENT>', },})

딥링킹 경로 (필수)

deeplinks를 사용해 운영체제와 데스크톱별로 유저를 딥링킹할 경로를 입력하세요. 모두 필수사항입니다.

주의하세요

deeplinks.android와 deeplinks.ios에 반드시 appScheme://host/path 형식의 URL 스킴 딥링크를 입력하세요. 인텐트 스킴 URL이나 http(s) URL을 사용하지 마세요.

폴백 경로 (필수)

fallbacks를 사용해 딥링킹이 실패했을 때 운영체제별로 유저를 보낼 폴백 경로를 입력하세요. 모두 필수사항입니다.

주의하세요

경로를 앱마켓으로 하려면 fallbacks.android와 fallback.ios에 각각 ‘google-play’와 ‘itunes-appstore’를 그대로 입력하세요. 다르게 입력하면 정상 동작하지 않습니다.

타입 (필수)

type을 사용해 웹 페이지 안에 버튼같은 CTA 요소가 있는지에 따라 값을 입력하세요. 필수사항입니다.

CTA 버튼 정보 (권장)

ctaParams를 사용해 리포트에서 조회할 CTA 버튼 정보를 입력하세요. 모두 선택사항입니다. 입력할 정보는 마케터에게 요청하세요. openDeeplink 함수 1개당 최대 3개를 입력할 수 있습니다. 정확한 성과 분석을 위해 모두 입력하는 것을 권장합니다.

CTA Param에는 버튼과 관련된 정보를 자유롭게 정의할 수 있습니다. 아래 예시를 참고하세요. 항목에 포함되지 않은 다른 사항도 정의할 수 있습니다.

캠페인 정보 (선택)

알립니다

유저가 아래와 같은 방법을 통해 웹 랜딩 페이지로 이동됐을 때는 터치포인트 정보가 수집되지 않습니다. 이러한 경우에는 리포트에서 터치포인트 그룹바이를 선택했을 때 defaultChannel과 defaultParams에 입력된 캠페인 정보가 조회됩니다.

  • 유저가 트래킹 링크나 UTM 파라미터가 적용되지 않은 광고 클릭

  • 유저가 직접 웹 랜딩 페이지 URL 입력

defaultParams를 사용해 에어브릿지 리포트에서 조회할 캠페인 정보를 입력하세요. 입력할 정보는 마케터에게 요청하세요. 자세한 내용은 가이드를 참고하세요.

기존 함수 참고사항

알립니다

openDeeplink 함수는 기존의 setDeeplinks, setDownloads, sendWeb 함수를 대체해 DOM 연결 없이 독립적으로 사용할 수 있는 함수입니다. 기존 함수는 추후 업데이트하지 않을 예정입니다. 따라서 openDeeplink 함수를 강력히 권장하며, 이미 기존 함수를 사용 중인 고객사만 아래 내용을 참고하세요.

스마트 배너 만들기

openBanner 함수를 사용해 웹 페이지에 스마트 배너를 만들 수 있습니다. 에어브릿지에서 제공하는 스마트 배너를 활용해 웹 랜딩 페이지에 간단하게 스마트 배너를 만들 수 있습니다. 아래 이미지는 스마트 배너의 기본 형식이며 제목, 설명, 버튼 이름 등을 변경할 수 있습니다.

배너 정보

아래 필드를 입력해 배너를 구성할 수 있습니다.

리다이렉션 정보

배너 정보 중 destination 필드를 입력해 버튼을 클릭한 유저를 어디로 리다이렉션할지 설정할 수 있습니다.

앱으로 딥링킹하기

유저를 앱으로 딥링킹하려면 아래처럼 설정하세요.

예시 코드입니다.

airbridge.openBanner({ title: '<BANNER_TITLE>', description: '<BANNER_DESCRIPTION>', buttonText: '<BANNER_BUTTON_TEXT>', color: '<BANNER_BUTTON_COLOR>', position: '<BANNER_POSITION>', // 'top' or 'bottom' destination: { type: 'deeplink', deeplinks: { android: '<YOUR_SCHEME>://...', ios: '<YOUR_SCHEME>://...', desktop: 'https://www.example.com/' }, fallbacks: { android: 'google-play', ios: 'itunes-appstore', }, }, ctaParams: { cta_param_1: '<EXAMPLE_CTA_PARAM_1>', cta_param_2: '<EXAMPLE_CTA_PARAM_2>', cta_param_3: '<EXAMPLE_CTA_PARAM_3>', }, defaultParams: { campaign: '<EXAMPLE_CAMPAIGN>', medium: '<EXAMPLE_MEDIUM>', term: '<EXAMPLE_TERM>', content: '<EXAMPLE_CONTENT>', },})

앱마켓으로 보내기

웹 페이지에 있는 유저를 앱마켓으로 보내려면 아래처럼 설정하세요.

예시 코드입니다.

airbridge.openBanner({ title: '<BANNER_TITLE>', description: '<BANNER_DESCRIPTION>', buttonText: '<BANNER_BUTTON_TEXT>', color: '<BANNER_BUTTON_COLOR>', position: '<BANNER_POSITION>', // 'top' or 'bottom' destination: { type: 'download', }, ctaParams: { cta_param_1: '<EXAMPLE_CTA_PARAM_1>', cta_param_2: '<EXAMPLE_CTA_PARAM_2>', cta_param_3: '<EXAMPLE_CTA_PARAM_3>', }, defaultParams: { campaign: '<EXAMPLE_CAMPAIGN>', medium: '<EXAMPLE_MEDIUM>', term: '<EXAMPLE_TERM>', content: '<EXAMPLE_CONTENT>', },})

웹 페이지로 보내기

웹 페이지에 있는 유저를 다른 웹 페이지로 보내려면 아래처럼 설정하세요.

예시 코드입니다.

airbridge.openBanner({ title: '<BANNER_TITLE>', description: '<BANNER_DESCRIPTION>', buttonText: '<BANNER_BUTTON_TEXT>', color: '<BANNER_BUTTON_COLOR>', position: '<BANNER_POSITION>', // 'top' or 'bottom' destination: { type: 'web', url: 'https://www.example.com', }, ctaParams: { cta_param_1: '<EXAMPLE_CTA_PARAM_1>', cta_param_2: '<EXAMPLE_CTA_PARAM_2>', cta_param_3: '<EXAMPLE_CTA_PARAM_3>', }, defaultParams: { campaign: '<EXAMPLE_CAMPAIGN>', medium: '<EXAMPLE_MEDIUM>', term: '<EXAMPLE_TERM>', content: '<EXAMPLE_CONTENT>', },})

스타일 정보

배너 정보 중 styles 필드를 입력해 배너 스타일을 변경할 수 있습니다. 키는 CSS 선택자(Selector) 형식이며, 에어브릿지에서 제공하는 아래 id를 사용해 스타일을 변경할 부분을 지정하세요. 변경할 값은 CSSStyleDeclaration (TypeScript) 형식을 참고해 지정하세요.

아래는 예시 코드입니다.

airbridge.openBanner({ ... styles: { '#airbridge-banner-icon': { borderRadius: '4px' } }})

추가 설정하기

구글 디지털 시장법(DMA) 준수

구글 디지털 시장법을 준수하기 위해서는 유저 동의 정보(User Consent)를 에어브릿지에 전달해야 합니다. 구글 디지털 시장법과 적용 대상 등에 대한 자세한 내용은 에어브릿지 가이드를 참고해 주세요.

주의하세요

2024년 3월 6일부터 EEA 지역에 있는 기존 유저와 신규 유저에 대한 유저 동의 정보를 최소 1회 수집해야 합니다.

에어브릿지 SDK로 유저 동의 정보를 수집하려면 다음 방법을 참고하세요.

초기화 시 유저 정보 설정하기

초기화 시 유저 정보를 전달하여, 발생하는 모든 이벤트에 유저 정보를 담을 수 있습니다.
설정한 유저 정보는 브라우저의 Local Storage에 남아 유저 정보를 초기화하기 전까지 모든 이벤트에 함께 전송됩니다.

airbridge.init({ app: '<YOUR_APP_NAME>', webToken: '<YOUR_WEB_TOKEN>', // ... user: { externalUserID: 'personID', externalUserEmail: 'persondoe@airbridge.io', externalUserPhone: '1(123)123-1234', attributes: { age_group: 30, gender: 'Female' }, alias: { custom_id: '83587901-2726-4E29-ACEB-A90B0F7E75F6', }, },})

캠페인 파라미터 설정하기

광고를 통해 웹 사이트에 랜딩한 경우, 웹 사이트 주소에 관련 정보를 파라미터로 붙이면, 그 정보를 토대로 웹 사이트 유입에 대한 트래킹이 가능합니다.

이벤트 전송 완료 대기하기

events.wait 함수를 통해 모든 이벤트 전송이 끝난 후의 동작을 보장할 수 있습니다. 이벤트 전송을 완료하기 전에 페이지를 이동하면 (예를 들어, 페이지를 빠르게 전환하는 중계 페이지에서 이벤트를 전송하는 경우 등) 이벤트가 유실될 수 있습니다. 이런 경우 events.wait 함수로 이벤트 전송을 완료할 때까지 대기한 후에 페이지를 이동하면 이벤트 유실을 최소화할 수 있습니다.

airbridge.events.send('category') airbridge.events.wait(3000, () => { location.href = '<TARGET_URL>'})

어트리뷰션 윈도우 수정하기

cookieWindow 옵션을 통해 일 단위로 어트리뷰션 윈도우를 설정할 수 있습니다. 기본 설정은 3일입니다.

airbridge.init({ app: '<YOUR_APP_NAME>', webToken: '<YOUR_WEB_TOKEN>', // ... cookieWindowInMinutes: <MINUTES>,})

cookieWindowInMinutes 옵션을 통해 분 단위로 어트리뷰션 윈도우를 설정할 수도 있습니다. cookieWindow 옵션과 중복 설정하면 cookieWindowInMinutes 옵션을 우선합니다.

airbridge.init({ app: '<YOUR_APP_NAME>', webToken: '<YOUR_WEB_TOKEN>', // ... cookieWindow: <DAYS>,})

웹 투 앱 어트리뷰션의 기여 기간 설정하기

useProtectedAttributionWindow 옵션을 통해 기여의 프로텍티드 어트리뷰션 윈도우(Protected Attribution Window, PAW)를 설정할 수 있습니다. 기본 설정은 true입니다.

  • useProtectedAttribution 옵션을 true로 설정하면, PAW를 적용합니다. 자세한 내용은 유저가이드를 참고하세요.

  • useProtectedAttribution 옵션을 false로 설정하면, PAW를 적용하지 않습니다. 자세한 내용은 유저가이드를 참고하세요.

airbridge.init({ app: 'YOUR_APP_NAME', webToken: 'YOUR_WEB_TOKEN', // ... useProtectedAttributionWindow: true,})

protectedAttributionWindowInMinutes 옵션을 통해 분 단위로 PAW를 설정할 수 있습니다. 기본 설정은 30분입니다. 최대 3일(4320분) 까지 설정할 수 있습니다. protectedAttributionWindowInMinutes 옵션은 useProtectedAttributionWindow 옵션을 true 로 설정했을 경우에만 작동합니다.

airbridge.init({ app: '<YOUR_APP_NAME>', webToken: '<YOUR_WEB_TOKEN>', // ... useProtectedAttributionWindow: true, protectedAttributionWindowInMinutes: 60,})

서브 도메인 간에 기여 정보 공유하기

에어브릿지 Web SDK는 기본적으로 기여 정보를 쿠키에 저장하고 있으며, 루트 도메인의 쿠키를 저장 공간으로 사용하고 있기 때문에, 서브 도메인 간에 기여 정보를 공유할 수 있습니다.

여러 서브 도메인을 사용한다면 shareCookieSubdomain 옵션을 통해 쿠키를 공유할 지 설정할 수 있습니다. shareCookieSubdomain 옵션은 false로 설정하면, 서브 도메인 사이에 데이터를 공유하지 않습니다. 기본 설정은 true입니다.

// initialize airbridge.init({ app: '<YOUR_APP_NAME>', webToken: '<YOUR_WEB_TOKEN>', // ... shareCookieSubdomain: false,})

알립니다

다음과 같은 상황을 고려하여 설정하세요.

  • 여러 서브 도메인에서 하나의 같은 서비스를 운영하는 경우에는 true로 설정하세요.

  • 여러 서브 도메인에서 각각 다른 서비스를 운영하는 경우에는 false로 설정하세요.

웹에서 트래킹 링크 생성하기

createTrackingLink 함수를 통해 트래킹 링크를 생성할 수 있습니다. 트래킹 링크란 유저가 발생시킨 터치포인트 데이터를 에어브릿지에 전달하기 위해 만드는 링크입니다.

트래킹 링크를 활용하여, 광고를 보거나 광고를 클릭한 유저를 원하는 목적지로 이동시킬 수 있습니다. 에어브릿지 대시보드에서는 트래킹 링크로 수집한 터치포인트 데이터를 활용하여, 전환에 기여한 채널을 분석할 수 있습니다.

interface Airbridge { createTrackingLink( channel: string, options: Record<string, boolean | number | string>, onSuccess: (trackingLink: TrackingLink) => void ): void createTrackingLink( channel: string, options: Record<string, boolean | number | string>, onSuccess: (trackingLink: TrackingLink) => void, onError: (error: Error) => void ): void}

createTrackingLink 함수로 생성된 트래킹 링크는 onSuccess 콜백을 통해 전달됩니다.

interface TrackingLink { shortURL: string qrcodeURL: string}

몰로코 쿠키 ID 수집하기

collectMolocoCookieID를 true로 설정하면, 몰로코 웹 캠페인을 통해 발생한 이벤트의 쿠키 ID를 자동으로 수집하여 캠페인을 최적화합니다.

airbridge.init({ app: '<YOUR_APP_NAME>', webToken: '<YOUR_WEB_TOKEN>', // ... collectMolocoCookieID: true,})

멀티 앱 사용하기

기본적으로 에어브릿지 Web SDK는 전역 airbridge 객체를 통해 사용할 수 있습니다. 하지만 특정 상황에서는 독립적인 SDK 인스턴스가 필요할 수 있습니다.

에어브릿지 Web SDK는 하나의 서비스에서 여러 Airbridge 앱을 동시에 사용할 수 있도록 지원합니다. createAirbridge 함수를 통해 새로운 인스턴스를 생성할 수 있습니다.

인스턴스 생성 및 초기화

전역 airbridge 객체 및 createAirbridge로 생성한 인스턴스들 모두 서로 독립적으로 동작하며, 초기화를 포함한 모든 SDK 기능을 독립적으로 사용할 수 있습니다.

웹 이벤트 전송하기

customInstance.events.send('category', { label: 'Tool', action: 'Hammer', value: 10, semanticAttributes: { currency: 'USD', transactionID: 'transaction_123', products: [ { productID: 'coke_zero', name: 'PlasticHammer', }, ], }, customAttributes: { promotion: 'FirstPurchasePromotion', },})