@boxfoxs/react-native-tracer

자체 어트리뷰션 서버(tracer)용 React Native SDK. 앱 설치가 어느 유입 경로에서 왔는지 귀속시킨다.

설치

yarn add @boxfoxs/react-native-tracer

peer dependency로 react-native, @react-native-async-storage/async-storage가 필요하다. 기기 정보는 주입받으므로 react-native-device-info를 쓰지 않는 앱도 연동할 수 있다.

사용법

// src/services/tracer.ts
import {createTracer} from '@boxfoxs/react-native-tracer';
import DeviceInfo from 'react-native-device-info';

export const tracer = createTracer({
  baseUrl: 'https://trk.compounding.co.kr',
  apiKey: 'tracer_sdk_myapp_2026',
  device: DeviceInfo, // 인터페이스를 구조적으로 만족하므로 그대로 넘긴다
  debug: __DEV__,
});

// 앱 루트 — 로그인 여부와 무관하게 항상 마운트되는 위치
useEffect(() => {
  tracer.reportAttribution();
}, []);

// 로그인 이후
useEffect(() => {
  if (user == null) {
    return;
  }
  tracer.setUserId(user.id);
  tracer.getCachedAttribution().then(attribution => {
    if (attribution == null) {
      return;
    }
    logger.setUserProperties({
      attribution_channel: attribution.channel,
      attribution_campaign: attribution.campaign,
      attribution_match_type: attribution.matchType,
    });
  });
}, [user]);

반드시 지킬 것

reportAttribution()은 앱 첫 실행 즉시, 로그인 여부와 무관하게 호출한다. 로그인 이후로 미루면 두 가지가 깨진다.

1. 설치만 하고 가입하지 않은 유저는 리포트가 아예 가지 않아 설치 수가 과소집계된다.
2. 가입까지 서버의 핑거프린트 매칭 윈도우(기본 24시간)를 넘기면 organic으로 떨어진다.

세션 내 중복 호출은 같은 Promise를 공유하므로 요청은 한 번만 나간다. 성공 결과는 저장소에 캐시되어 다음 실행부터는 네트워크를 타지 않는다.

Android Install Referrer

Android는 Play Install Referrer로 100% 정확하게 귀속된다. SDK가 이를 위해 getInstallReferrer()가 준비될 때까지 최대 referrerTimeoutMs(기본 10초) 폴링한다.

react-native-device-info의 getInstallReferrer는 SharedPreferences를 동기로 읽기만 하고, 값을 채우는 InstallReferrerClient는 앱 시작 시 비동기로 Play 서비스에 연결한다. 준비 전에 읽으면 'unknown'이 돌아오므로 폴링이 필요하다.

준비되지 않은 상태로 리포트하면 서버가 기기 단위로 멱등 처리하기 때문에 organic으로 확정된다. 그래서 SDK는 referrer가 해소되지 않으면 null을 돌려주고 리포트를 다음 실행으로 미룬다. referrerMaxAttempts(기본 3) 회를 넘기면 사이드로드·에뮬레이터로 판단해 referrer 없이 전송한다.

organic 으로 굳은 기기 되살리기

이 SDK 이전 버전(폴링 없이 바로 전송)을 깐 기기는 이미 organic으로 확정돼 있다. referrer 자체는 기기에 계속 남아 있으므로, 캐시된 결과가 organic이고 Android라면 기기당 딱 한 번 referrer를 다시 읽어 재리포트한다. 서버가 install_referrer로 승격하면 캐시도 갱신된다.

딱 한 번인 이유는 비용이다. 매 실행마다 하면 진짜 organic 유저 전원이 앱을 켤 때마다 최대 10초 폴링과 요청 하나를 물게 된다. 진짜 organic은 재리포트해도 판정이 그대로라 캐시를 건드리지 않는다.

서버에 승격 로직(team-bake/tracer#3)이 있어야 효과가 난다. 없으면 서버가 기존 판정을 그대로 돌려주므로 무해하게 넘어간다.

iOS

iOS에는 Install Referrer에 해당하는 수단이 없다. 서버의 핑거프린트 매칭은 클릭 시점의 브라우저 UA와 설치 시점의 WebView UA가 달라 신뢰도가 낮다. iOS 귀속은 딥링크 기반으로 별도 설계가 필요하며, 이 SDK만으로는 해결되지 않는다.

서버 준비물

앱을 새로 붙이려면 tracer 서버 쪽에 다음이 있어야 한다.

1. app 레코드 — 앱 이름, bundle id, 플랫폼
2. api_key 레코드 — 해당 app에 묶인 키, permissions에 sdk:report 포함
3. 유입 링크 — channel/campaign과 함께 생성. android_url을 Play스토어 URL로 반드시 채울 것. 비워두면 destination_url로 폴백해 스토어를 거치지 않고, Install Referrer가 생성되지 않는다.

API

| 메서드 | 설명 | |---|---| | reportAttribution() | 설치 리포트. 앱 첫 실행 즉시 호출 | | getCachedAttribution() | 캐시된 귀속 결과. 리포트를 유발하지 않음 | | setUserId(userId) | 로그인 후 앱 유저 ID를 전환에 연결 | | reset() | 캐시 초기화. 테스트용 |

설정

| 옵션 | 기본값 | 설명 | |---|---|---| | baseUrl | (필수) | tracer 서버 주소 | | apiKey | (필수) | 앱별 SDK 키 | | device | (필수) | 기기 정보 접근자. 보통 DeviceInfo | | storage | AsyncStorage | 영속 저장소 | | referrerTimeoutMs | 10000 | Install Referrer 폴링 제한 | | referrerMaxAttempts | 3 | referrer 없이 강행하기까지 허용할 실행 횟수 | | storagePrefix | @tracer | 저장소 키 접두사 | | debug | false | 디버그 로그 |