임베드 문서

iframe으로 앱 정보를 띄우는 방법과 파라미터를 설명합니다.

개요

임베드는 iframe에 넣는 페이지입니다. 대시보드와 같은 화면들(앱 정보·검색·인기 차트·카테고리·유사 앱·뉴스)을 그리며 키가 필요 없습니다. 아래의 모든 것이 URL로 결정됩니다.

앱 하나를 읽는 모드(info·similar·news)는 API와 같은 방식으로 앱을 가리킵니다. 스토어를 고르고 그 스토어의 식별자를 최소 하나 넘깁니다. search는 검색어만 받고, chart와 category는 아무것도 필요 없습니다.

모드

경로가 프레임에 무엇을 그릴지 결정합니다. 경로 없는 /embed는 앱 정보를 뜻하며, 기존 임베드 URL이 이렇게 해석됩니다.

/embed/search — 키워드 검색. 요약 카드로 그립니다.
/embed/chart — 스토어 인기 차트입니다. 무료·유료·매출, 전체 스토어 또는 카테고리 하나(id는 categories 엔드포인트 값)를 그립니다.
/embed/category — 카테고리 목록. 타일을 누르면 해당 카테고리의 차트가 열립니다.
/embed/info — 앱 전체 상세. 아래 sections 파라미터로 구성합니다.
/embed/similar — 스토어가 해당 앱과 함께 추천하는 앱 목록.
/embed/news — 해당 앱에 대한 최신 기사.

URL 파라미터

스토어와, 앱 하나를 읽는 모드에서의 식별자를 뺀 나머지는 전부 선택입니다. 스토어도 생략하면 play-store로 읽습니다.

store — 어느 스토어에서 읽을지.
<identifier> — 앱 식별자입니다. play-store는 package_name, app-store는 track_id 또는 bundle_id, microsoft-store는 product_id 또는 package_family_name을 받습니다. 앱 하나를 읽는 화면에서 필수입니다.
immediately — 도착하자마자 조회합니다. 이동해 가는 주소에서 의미가 있으며, API의 embed 필드로 만든 링크에는 이미 붙어 있습니다.
query — 검색어. search 모드 전용.
count — 목록 모드가 반환할 개수.
content_type — chart·category가 조회할 목록.
pricing_type — 차트 종류입니다. grossing은 chart 모드 전용이며 Microsoft Store에는 매출 차트가 없습니다.
id — 차트를 카테고리 하나로 좁힙니다. 생략하면 스토어 전체.
sections — info 모드가 무엇을, 어떤 순서로, 어떤 옵션으로 그릴지.
<mode>_items — 해당 모드의 결과 카드가 그릴 부분. 예: chart_items=icon,name. 모드별로 나뉘어 있어 URL 하나로 이동해 갈 모든 화면을 각각 꾸밀 수 있습니다. 생략하면 전부 그립니다.
<mode>_heading — 해당 모드 목록 위의 제목 문구("…에 대한 검색 결과"). 예: similar_heading=0. 0이면 숨기고, 다른 문자열이면 그 문구로 바꿉니다. search · similar · chart · news 전용.
lang / country — 어느 지역 스토어를 어느 언어로 읽을지.
ui_lang — 인터페이스 언어(제목·버튼·안내문)입니다. 위의 스토어 언어와 별개로, 생략하면 조회에 쓴 lang을 따르고 auto는 읽는 사람의 브라우저 언어를 따릅니다. 그 외 코드는 해당 언어로 고정되며 수십 개 언어를 지원하고, 지원되지 않는 값은 영어로 표시됩니다.
color — 링크·차트·버튼에 쓰이는 강조색. rgb()·hsl() 형식은 퍼센트 인코딩해서 넣습니다.
appearance — 고정하지 않으면 보는 사람의 테마를 따릅니다.
paging — 목록과 리뷰가 첫 페이지 이후 이어지는 방식입니다. scroll은 끝에 닿으면 자동으로 더 불러옵니다. button은 누를 때만 불러와 고정 높이 프레임에 알맞습니다. off는 첫 페이지에 머뭅니다. 생략하면 임베드 목록은 고정되고 리뷰는 위치에 따라 자동입니다.
nav — 임베드가 다른 화면으로 이동하지 않게 합니다. 화살표가 사라지고 결과 카드도 다른 앱을 열지 않습니다. 다만 히스토리가 쌓이면(예: 호스트의 go) 프레임의 뒤로 가기 화살표는 나타납니다.
scrollbar — 스크롤바를 그릴지, 언제 사라질지. 사라지는 시점은 페이지 바에만 적용됩니다.
scrollbar_size — 바의 두께.
scrollbar_color — theme는 위의 강조색을 따라가므로 color를 바꾸면 바도 함께 바뀝니다. hex를 주면 그 값으로 고정됩니다.
embed_token — 임베드 안에서 관리 기능을 엽니다. 아래 '관리 임베드' 참조. 세션은 어느 화면에서든 열리고 이동해도 유지됩니다. 관리 기능은 앱 화면에 나타나고, 브랜딩 제거는 모든 화면에 적용됩니다.

sections 파라미터

섹션 이름을 콤마로 나열하며 적은 순서대로 그려집니다. 이름 뒤 괄호에 그 섹션의 설정을 담을 수 있습니다.

괄호 안에서는 순서가 의미를 갖지 않습니다. 그냥 쓴 단어는 항목, key=value는 옵션, @는 윈도입니다. 같은 섹션을 여러 번 쓸 수 있습니다. 차트와 기간이 각각 다른 analytics 블록 셋을 두는 건 정상적인 사용입니다.

모르는 이름이나 그 스토어에 없는 필드는 오류를 내지 않고 건너뜁니다.

head — 섹션 제목을 없앱니다.
title — 제목을 바꿉니다.
id — 이 블록에 이름을 붙입니다. scroll-to에서 씁니다.
count — 보여줄 개수. similar와 news 전용이며 기본값은 각각 10과 5입니다.
viewer — preview 전용. 크게 보기를 통째로 끕니다. 확대 버튼이 사라지고 스크린샷을 눌러도 뷰어가 열리지 않습니다.
fullscreen — preview 전용. 크게 보기를 화면 안 오버레이로만 엽니다. 브라우저 전체 화면 전환이 없고, 영상 컨트롤과 유튜브의 전체 화면 버튼도 제거됩니다. 허용 상태(기본)에서는 iframe 자체에 allowfullscreen이 있어야 하며, 위 코드에 포함돼 있습니다.
autoplay — preview 전용. 인라인 영상이 스스로 재생되지 않고 재생 버튼 뒤에서 기다립니다.
picker — analytics 전용. 기간 선택을 숨겨 차트를 블록의 기간에 고정합니다. 보이는 상태(기본)에서는 방문자가 일 프리셋, 주, 월, 연도, 직접 지정 기간으로 바꿀 수 있습니다.
translate — reviews 전용. AI 번역 버튼을 숨깁니다. 임베드 안에서 번역 버튼은 reply:translate 권한을 가진 키가 있을 때만 나타납니다. 번역은 임베드 키 소유자의 일일 AI 사용량을 소모하므로, 방문자에게 노출할지는 호스트가 정합니다.
tabs — reviews 전용. 정렬 탭을 숨겨 순서를 고정합니다.
sort — reviews 전용. 목록이 처음 열릴 때의 정렬.

알아둘 것

모든 임베드 하단에는 작은 app·atlas 로고가 붙고 이곳으로 링크됩니다. 유료 플랜 소유자의 임베드 키를 붙이면 브랜딩이 제거됩니다. 단, 페이지의 출처가 키의 허용 도메인에 있어야 합니다(관리 기능과 같은 검사). 권한이 하나도 없는 키도 이 용도로는 세션이 열리므로, 브랜딩 제거를 위해 데이터나 기능을 페이지 방문자에게 노출할 필요가 없습니다.
기록은 앱을 관측한 시점까지 거슬러 갑니다. 그보다 과거에서 시작하는 구간은 있는 만큼만 그려집니다.
옵션 값 안의 콤마·괄호는 두 번 퍼센트 인코딩해야 합니다(콤마는 %252C). 브라우저가 쿼리를 한 번 디코드한 뒤에 sections 문법을 읽기 때문입니다. 값 안의 =와 @는 그대로 써도 되며, 단독 항목 앞의 @만 윈도로 해석됩니다. 대시보드의 임베드 생성기는 자동으로 처리합니다.
analytics는 관측 중인 앱에만 그려집니다. 스냅샷이 없는 앱은 대신 안내가 표시됩니다.
공식 지표(installs, sessions, proceeds, crashes 등)는 analytics 안에 카드 플래그로 구분되어 그려지며, 키가 관리하는 앱에서 관리 토큰(embed_token)이 있어야 합니다. 없으면 자리도 차지하지 않습니다.
totalInstalls와 installs는 서로 다른 값이며, 한쪽 이름이 다른 쪽을 그리지 않습니다. totalInstalls는 누적 설치 수입니다. Play 게시물에 공개돼 매일 스냅샷으로 쌓이는 값이며, 관리 권한이 있으면 스토어 자체 누적치도 같은 카드에 함께 그려집니다. installs는 그날의 신규 설치 수이며 스토어 자체 통계에서만 옵니다. App Store는 게시물에 설치 수를 공개하지 않아 totalInstalls로는 아무것도 그려지지 않습니다.

App Atlas · API 문서 · SDK 문서 · 이용약관 · 개인정보처리방침 · Sign up

en · zh