Unity Ads 연동

베타

Unity Ads 연동은 실제 광고주 계정으로 검증 중입니다. adstage 수치가 Unity 콘솔과 다르면 알려 주세요.

adstage에서는 Unity Ads의 캠페인 비용을 수집하고, 트래킹 링크로 유입된 클릭·설치·구매를 unity.ads 채널로 집계하며, 설치와 구매를 Unity로 다시 보낼 수 있습니다. Unity Ads는 로그인(OAuth) 연동이 아니라 Unity Cloud에서 발급한 서비스 계정 키를 adstage에 입력해 연동합니다.

1. 연동 개요

adstage 대시보드 연동 > 광고 채널 연동 > Unity Ads에서 연동하면 다음 세 가지가 함께 동작합니다.

참고하세요

ironSource Ads 직접 광고(direct demand)는 2026년 4월 30일에 종료되었고(신규 계정·캠페인 생성은 4월 15일 중단), Unity는 광고주에게 Unity Ads로 옮기라고 안내합니다. adstage는 ironSource Ads 연동을 제공하지 않으므로 Unity Ads 연동을 사용해 주세요.

2. Unity에서 키 발급받기

Unity Ads 비용은 Unity의 Advertising Statistics API로 읽습니다. 이 API는 서비스 계정의 Key ID와 Secret key로 인증합니다. 같은 순서가 adstage의 Unity Ads 키 발급 방법 안내 상자에도 표시되며, Unity Ads 키 발급 페이지 열기 버튼으로 Unity Cloud를 바로 열 수 있습니다.

1. Unity Cloud에서 Manage organization(조직 관리) > Administration > Service Accounts로 이동해 서비스 계정을 만듭니다. 조직 Owner 또는 Manager만 만들 수 있습니다.

2. 서비스 계정에 조직 역할 Growth > Advertise Stats API Viewer를 추가합니다. 이 역할이 없으면 adstage가 키를 등록할 때 Unity가 요청을 거부합니다.

3. 서비스 계정 상세 화면에서 Create key를 눌러 Key ID와 Secret key를 복사해 둡니다. Secret key는 이때 한 번만 보이며, 잃어버리면 키를 새로 만들어야 합니다.

4. Unity 유저 획득(Acquire) 대시보드의 Settings에서 Organization core ID를 복사합니다. adstage의 조직 ID 칸에 넣는 값입니다.

주의하세요

• Settings 화면에는 Organization ID 칸이 따로 있습니다. adstage에 넣을 값은 Organization core ID입니다.
• Unity 문서에는 측정 업체(MMP)가 서비스 계정을 요청할 때 쓰는 Advertise Stats API MMP Viewer 역할도 있습니다. adstage는 광고주가 직접 만든 서비스 계정을 쓰므로 Advertise Stats API Viewer를 추가하면 됩니다.

3. adstage에 계정 등록하기

1. 연동 > 광고 채널 연동 > Unity Ads에서 비용 연동 탭을 엽니다.

2. Unity Ads 비용 연동 스위치를 켭니다. 스위치가 꺼져 있으면 연동 계정 추가 버튼을 누를 수 없습니다.

3. 연동 계정 추가를 클릭하고 다음 항목을 입력합니다.

4. 연동을 클릭합니다. adstage가 저장 전에 입력한 키로 Unity에 하루치 리포트를 한 번 조회해 키가 유효한지 확인합니다(버튼이 인증 중...으로 바뀝니다). 확인이 끝나면 "Unity Ads 계정이 성공적으로 추가되었습니다" 메시지가 뜨고 최근 30일 데이터의 첫 수집이 바로 시작됩니다.

연동 단계에서 표시되는 오류 메시지

4. 연동 계정 관리하기

등록한 계정은 비용 연동 탭의 목록에 계정명, 상태, 데이터가 업데이트된 최근 일시, 관리 열로 표시됩니다.

• 준비 중: 등록 직후 첫 수집이 진행 중입니다. 보통 몇 분 안에 끝납니다.
• 성공: Unity API 연결이 정상입니다. 광고를 집행하지 않아 수집된 행이 0건이어도 연결이 정상이면 성공으로 표시됩니다.
• 실패: Unity가 키를 거부했습니다(키 삭제, 역할 회수 등). 표시에 마우스를 올리면 오류 내용을 볼 수 있습니다. 요청 제한(429)이나 일시 오류는 상태를 바꾸지 않고 다음 주기에 자동으로 다시 시도합니다.

비용 데이터가 3일 넘게 저장되지 않으면 상태 옆에 경고 표시와 함께 조치 필요 안내("N일째 광고비 데이터가 수집되지 않았습니다")가 나타나고, 수집이 재개되면 자동으로 사라집니다.

키를 교체하거나 연동을 해제하려면 관리 열의 삭제 아이콘으로 계정을 삭제합니다. 이미 수집된 데이터는 남고 새 데이터만 수집되지 않습니다. 등록한 키를 화면에서 수정하는 기능은 없습니다.

5. 트래킹 링크 만들기

딥링크 > 생성에서 광고 채널로 Unity Ads를 고르면 캠페인·광고소재 칸에 Unity 매크로가 자동으로 채워집니다. 그대로 두면 Unity가 클릭할 때 실제 값으로 바꿔 줍니다. Unity에는 광고 그룹 단계가 없으므로 광고 그룹 칸은 비워 둡니다.

ifa_raw·gamer_id·unity_game_id와 ID 매크로는 입력 여부와 관계없이 항상 붙습니다. 생성된 링크는 다음과 같은 형태입니다.

https://adg.im/@{조직}/track/unity.ads?short_path={링크경로}&campaign={campaign_name}&campaign_id={campaign_id}&ad_creative={creative_pack}&ad_creative_id={creative_pack_id}&sub_channel={source_app_id}&ifa_raw={ifa}&gamer_id={gamer_id}&unity_game_id={game_id}

Unity는 클릭마다 바뀌는 클릭 ID 매크로를 제공하지 않습니다. 트래킹 링크의 클릭 ID는 adstage가 발급하고, 매체사 포스트백을 켜면 gamer_id를 Unity와의 매칭 키로 씁니다.

복사한 링크는 Unity 유저 획득 대시보드의 앱 어트리뷰션 링크 설정에 플랫폼별로 넣습니다. 저장할 때 Unity가 URL 형식을 검사합니다. 메뉴 위치를 찾기 어려우면 Unity 담당자에게 문의하세요.

주의하세요

• 링크의 {ifa}·{gamer_id}·{game_id} 매크로를 지우거나 바꾸지 마세요. {ifa}가 없으면 Unity가 링크 저장을 거부하고, 나머지 두 값이 없으면 설치 포스트백을 보낼 수 없습니다.
• Unity는 어트리뷰션 링크가 https여야 하고, 리다이렉트는 HTTP 3xx 방식이어야 하며, App Store·Google Play로 리다이렉트하면 안 된다고 요구합니다. 리다이렉트 설정의 대상은 스토어가 아닌 웹 랜딩 페이지로 두세요.
• 캠페인 이름은 Unity가 채워 주므로 비용과 전환이 같은 캠페인 행으로 합쳐집니다. 이름을 직접 입력했다면 Unity 캠페인 이름과 똑같이 써야 합니다.

6. Unity로 전환 보내기

Unity는 MMP 없이 광고주가 직접 보내는 설치·인앱 이벤트 포스트백 규격을 공개합니다. 링크의 매체사 포스트백을 켜면 Unity Ads 채널 링크에는 매체 프리셋 Unity Ads — Install & purchase (custom integration)가 자동으로 채워집니다. 비어 있으면 매체 프리셋에서 직접 고르세요. 설정 항목 설명은 매체사 포스트백을 참고하세요.

• {unity_game_id}·{campaign_id}는 Unity가 클릭할 때 링크에 채운 값을 그대로 돌려줍니다. 따로 입력할 것이 없습니다.
• {bundle_id}는 딥링크 설정에 등록한 Android 패키지명(App Links)과 iOS 번들 ID(Universal Links)에서 읽습니다. 구매 포스트백을 쓰려면 링크 설정에 두 값이 등록되어 있어야 합니다.
• {install_ts}는 설치 시각, {tracking_enabled}는 광고 ID를 쓸 수 있으면 1, 아니면 0이 들어갑니다. {revenue}·{currency}에는 구매 이벤트의 금액과 통화가 들어갑니다.
• install은 first_open도 함께 인식합니다.
• Unity가 받는 인앱 이벤트명은 purchase, ad_revenue, session 세 가지입니다. adstage의 purchase는 이름 그대로 전송되므로 이벤트명 매핑은 비워 둡니다. Unity가 받지 않는 이벤트는 추가하지 마세요.

주의하세요

• 설치 포스트백은 CPI 과금의 근거입니다. Unity는 설치 포스트백으로 받은 설치를 기준으로 설치 수를 집계하므로, 트래킹 링크와 설치 포스트백을 함께 설정해야 Unity 콘솔과 adstage 비용 리포트에 설치·비용이 제대로 잡힙니다.
• 이벤트 최적화 캠페인(Retention·Payer·Level Complete)은 Unity가 지정한 MMP(Adjust·AppsFlyer·Singular)로만 운영할 수 있습니다. 커스텀 연동으로는 이 캠페인 유형을 쓸 수 없으며, Unity는 커스텀 연동 문제를 지원하지 못할 수 있다고 안내합니다.
• Unity는 귀속되지 않은 설치까지 모두 보내는 전체 공유를 권장하지만, adstage 매체사 포스트백은 해당 링크로 귀속된 이벤트만 attributed=1로 보냅니다.

7. 수집되는 데이터

비용 연동으로 수집되는 데이터는 Unity가 보고한 값이며, 일별·캠페인 단위로 저장됩니다.

리포트에서는 매체 보고 값이라는 뜻으로 지표 이름에 **(Channel)**이 붙습니다.

지출·노출·클릭·설치가 모두 0인 날은 저장하지 않습니다. 캠페인은 캠페인 ID로 구분하므로 Unity 콘솔에서 캠페인 이름을 바꿔도 같은 캠페인으로 이어집니다.

8. 주의사항

아래 사항을 주의해 주세요.

• Unity Ads와 adstage 간에 수치 차이가 발생할 수 있습니다. Unity 리포트는 UTC 기준이고, 집계 시점과 통화 환산 기준도 다르기 때문입니다.
• CPI 과금 캠페인은 Unity가 집계한 설치 수에 따라 비용이 정해지므로, 설치 포스트백이 늦게 도착하면 과거 일자의 비용이 나중에 바뀔 수 있습니다. 최근 30일을 다시 가져올 때 반영됩니다.
• Unity Statistics API는 조직 ID당 1초에 1회, 30분에 30회까지만 호출할 수 있습니다. 같은 조직 ID로 다른 도구가 API를 많이 호출하면 수집이 지연될 수 있으며, adstage는 자동으로 다시 시도합니다.
• 서비스 계정 키를 삭제하거나 역할을 회수하면 수집이 중단되고 상태가 실패로 바뀝니다.
• Unity Ads 비용 연동 스위치를 끄면 이 조직의 모든 Unity 계정 수집이 중단됩니다. 계정 정보는 남아 있으므로 스위치를 다시 켜면 수집이 재개됩니다. adstage는 Unity 리포트를 읽기만 하며 캠페인 설정을 변경하지 않습니다.

9. 문제 해결

연동 과정에서 문제가 발생하면 다음 사항을 확인해 주세요.

키 등록이 안 될 때

1. 역할 확인: 서비스 계정에 Growth > Advertise Stats API Viewer 역할이 추가되었는지 확인
2. 조직 확인: 조직 ID에 넣은 값이 Settings의 Organization core ID이고, 서비스 계정을 만든 조직의 것인지 확인
3. 키 확인: Secret key를 발급 직후 복사한 값 그대로 넣었는지 확인. 분실했다면 키를 새로 발급
4. 다시 시도: "연결하지 못했습니다" 메시지는 일시 오류이므로 잠시 후 다시 시도

상태는 성공인데 데이터가 없을 때

1. 집행 확인: 최근 30일에 Unity 캠페인 지출이 있는지 Unity 콘솔 리포트와 대조
2. 주기 확인: 첫 수집은 등록 직후 시작되며, 이후 4시간마다 최근 30일(당일 제외)이 갱신됩니다. 오늘 데이터는 내일 업데이트부터 들어옵니다
3. 설치 포스트백 확인: CPI 캠페인은 Unity가 받은 설치를 기준으로 과금되므로, 포스트백이 없으면 비용이 0으로 남을 수 있음

포스트백이 Unity에 도착하지 않을 때

1. 링크 확인: 트래킹 링크에 gamer_id·unity_game_id·ifa_raw 파라미터가 그대로 남아 있는지 확인
2. 설정 확인: 해당 링크의 매체사 포스트백이 켜져 있고 클릭 ID 파라미터가 gamer_id인지 확인
3. 앱 정보 확인: 구매 포스트백에는 bundle_id가 필요하므로 링크 설정에 Android 패키지명과 iOS 번들 ID가 등록되어 있는지 확인
4. 귀속 확인: 포스트백은 그 링크로 귀속된 설치·구매에만 발사됩니다

추가 지원이 필요한 경우 adstage 고객지원팀에 문의해 주세요.

10. 자주 묻는 질문

Unity에 adstage를 MMP로 등록해야 하나요?

아니요. Unity는 광고주가 직접 보내는 커스텀 연동을 공식 허용하므로 별도 등록 없이 비용 수집·트래킹 링크·포스트백을 쓸 수 있습니다. 단, 이벤트 최적화 캠페인은 Unity 지정 MMP가 필요합니다.

Unity 조직이 여러 개입니다.

조직마다 서비스 계정 키를 만들어 계정을 하나씩 추가하세요. 같은 조직 ID는 한 번만 등록할 수 있습니다.

커스텀 링크의 채널 이름은 어떻게 써야 하나요?

unity, unityads, unity_ads, unity ads는 모두 리포트에서 unity.ads로 집계됩니다.

전환수 (Channel)과 adstage 설치 수가 왜 다른가요?

전환수 (Channel)은 Unity가 자체 기준으로 귀속한 설치이고, adstage 설치는 트래킹 링크와 SDK로 측정한 값입니다. 집계 기준과 시간대가 달라 차이가 납니다.

11. 참고 문서

• Unity Advertising Statistics API v2 — 서비스 계정 인증, Advertise Stats API Viewer 역할, 요청 제한, 지표·분해 항목
• Unity Cloud 서비스 계정 만들기
• 어트리뷰션 링크 매크로(Dynamic custom tokens) — 매크로 목록과 https·리다이렉트 요구사항
• 커스텀 연동 어트리뷰션 링크 보내기
• 커스텀 연동 설치 포스트백 파라미터
• 커스텀 연동 인앱 이벤트 포스트백
• 설치 후 이벤트 데이터와 최적화 캠페인 — 이벤트 최적화 캠페인의 MMP 요건
• ironSource Ads 직접 광고 종료 안내