앱 추천정보 연결

Android

SAIRO는 Google Play 주소에 서명된 추천정보를 붙입니다. 최초 실행 시 Install Referrer로 읽어 본인 서버에 전달하세요. 실패하면 추천코드 입력으로 연결합니다. 직접 APK 설치·다른 스토어에는 이 자동 경로가 적용되지 않습니다.

Kotlin 보조 코드 · Google 공식 설정

앱 build.gradle에 implementation("com.android.installreferrer:installreferrer:2.2")를 추가하고, 최초 실행에 readInstallReferrer를 호출합니다. App Links 수신 시 capture(intent.data), 직접 입력 시 enterCode를 호출하세요.

iPhone

이미 설치된 앱은 본인 도메인의 Universal Links를 설정하고 capture(url)를 호출합니다. App Store 설치 후 자동 복원은 제공하지 않습니다. 설치 전 복사한 추천코드를 앱의 입력란에 붙여넣도록 구현하세요.

광고주 서버

앱이 받은 pending을 본인 서버로 보냅니다. 서명 토큰이면 verifyReferral, 추천코드이면 resolveAppReferral를 호출한 뒤 반환된 토큰을 verifyReferral로 검증하세요. 서버 키를 앱이나 브라우저에 넣지 않습니다.

const userRef = customerReference(customer.id, secret);
const result = await resolveAppReferral(code, {
  secret, campaignId, userRef, testOnly: isIntegrationTest // 연결 시험: true, 실제 고객 귀속: false
});
if (!result.ok) throw new Error(result.result.code); // retry:true면 재시도
const attribution = verifyReferral(result.result.referral, {
  secret, campaignId, version, windowDays, allowTest: isIntegrationTest
});
// isIntegrationTest는 서버의 별도 테스트 경로에서 결정하세요. 앱이 보낸 값을 그대로 신뢰하지 마세요.
// 회원/설치 기록과 attribution(test_only 포함)을 DB 트랜잭션으로 고정.
// 기존 귀속을 덮어쓰지 말고 네트워크 재시도는 멱등 처리.

userRef는 서버가 로그인 회원 또는 안정적인 설치 기록에서 계산하세요. 클라이언트가 임의로 보내는 값을 믿으면 안 됩니다. 회원가입이 필요 없는 최초 실행 목표에는 서버의 설치 식별자를 사용하고, 이후 고객과의 연결 정책도 직접 구현해야 합니다.

성과 전송과 테스트

추천코드 연결은 성과 접수가 아닙니다. 실제 신규 가입·최초 실행·결제를 서버가 확인한 뒤 sendConversion으로 전송하세요. 재설치·기존 가입·갱신 결제의 제외 판단은 광고주 원본 기록이 필요합니다. SAIRO가 광고주 DB를 대신 조회하지 않습니다.

먼저 resolveAppReferral(...,{testOnly:true})와 testConversion을 사용합니다. 테스트 조회는 코드 귀속·성과·예산 예약을 만들지 않습니다. 실제 테스트 클릭이 있어야 attribution=true를 검증할 수 있습니다. 캠페인 설정의 연결 테스트에서 테스트 전용 링크를 만드세요. 연결 대기·예산 0원이어도 테스트할 수 있고 실제 클릭·성과·광고비에는 반영되지 않습니다. 테스트 토큰은 verifyReferral의 allowTest:true로 명시적으로 검증하고 testConversion으로만 전송하세요. 실제 배포 앱 설치 검증은 별도로 진행하세요.

API: POST /api/service/app-referral/resolve. JSON: campaign_id, code, user_ref, test_only(boolean). 서명: x-sairo-timestamp(밀리초), x-sairo-signature(HMAC-SHA256(timestamp+'.'+원문)). 만료·다른 고객 재사용·다른 캠페인 코드·잘못된 서명은 거절됩니다.

재시도: 429/5xx/네트워크 실패에는 동일 요청을 재시도하세요. 401은 키/시각, 422는 코드/만료, 409는 이미 연결된 고객을 확인하세요. 앱 pending은 본인 서버 저장 성공 후에만 acknowledge로 삭제하세요.

출시 전 확인

1. Android Play 테스트 트랙에서 링크 → 신규 설치 → 최초 실행 → 서버 검증.
2. iPhone 신규 설치 → 코드 입력 → 서버 검증, 기존 설치 → Universal Link.
3. 같은 코드 다른 고객, 만료 코드, 중복 완료, 재설치, 기존 고객, 네트워크 재시도.
4. 결제 취소·환불 상태와 실제 원본 기록, 서버 키 노출 여부.

보조 코드의 SAIRO 서버 동작과 실제 스토어·광고주 앱 동작은 별도의 검증입니다. 실제 단말 설치 테스트 전에는 완료로 표시하지 않습니다.