개요

본 문서는 원스토어 앱의 URL Scheme 연동 및 각종 API를 설명합니다.

원스토어 앱 URL Scheme 연동

모바일 애플리케이션 및 브라우저에서 원스토어 클라이언트를 실행시킨 후 특정 다운로드 페이지로 바로 이동하거나 검색을 실행시키는 URL scheme이 지원됩니다. http://, ftp://, market:// 과 같은 문자열을 URL scheme이라 부릅니다. URL scheme을 통해 앱이 실행되는 방식은 다음과 같습니다.

• 앱이나 웹페이지에서 하이퍼링크 클릭 시 URL scheme이 system에 전달됨
• system에서 전달된 URL scheme을 보고 실행 가능한 앱이 있는지 확인
• 해당 URL scheme을 받을 수 있는 앱이 있다면 앱을 실행시키며 이 URL을 함께 전달
• 앱이 실행되면서 URL에 포함된 내용을 참조해서 특정 기능을 수행함

웹 페이지에서 URL scheme을 이용해 원스토어 클라이언트를 실행하는 경우, 원스토어 클라이언트가 미설치된 경우에 대한 예외 처리 구현이 필요할 수 있습니다. (단, Shorten URL 방식은 예외 처리가 필요하지 않습니다)

URL scheme 구성

각 호출 규격 상세 내용은 레퍼런스를 참고한다.

앱/게임 상세호출

상품뷰는 product ID(상품ID)를 기준으로 원스토어 클라이언트에서 해당 상품의 상세보기 화면으로 이동합니다. 상품PID는 원스토어 웹페이지에서 해당 상품을 검색하면 간단하게 확인 가능합니다. 예를 들어, '드래곤삼국지'라는 게임을 검색하여 해당 게임의 상세페이지로 이동한 후 PC 브라우저 상단의 URL을 확인하시면 http://onestore.co.kr/userpoc/game/view?pid=0000722708와 같은 형태로 보이는데, 여기서 0000722708이 이 게임의 상품PID입니다.

규격

onestore://common/product/{상품PID}

샘플

onestore://common/product/0000252337

검색호출

검색뷰는 원스토어 클라이언트가 해당 검색어에 대한 검색결과 화면을 보여주게 합니다.

규격

onestore://common/search/{검색어}

샘플

onestore://common/search/네이버앱

업데이트 요청(자동설치)

앱/게임 상품의 업데이트 요청을 받아, 해당 상품이 최신 버전이 아닌 경우 자동으로 업데이트 버전을 다운로드 및 설치합니다. 업데이트 요청을 하는 상품의 PKG명과 다운로드 할 상품의 PKG명이 동일한 경우에 동작합니다.

규격

onestore://common/product/bg_update/{상품PID}

샘플

onestore://common/product/bg_update/0000252337

Shorten URL로 연동하기

ProductID(상품PID)를 활용해서 간단하게 앱 상세페이지 연동 주소를 생성할 수 있습니다. HTTP 랜딩 방식이므로 원스토어 클라이언트 설치 유무에 관계없이 모두 동작합니다. (원스토어 클라이언트가 설치되어 있지 않은 단말에서는 원스토어 모바일웹의 해당 상품 상세보기로 이동합니다.)

규격

https://onesto.re/{상품PID}

샘플

https://onesto.re/0000252337

기존 규격의 Redirects 처리

기존에 각 Store에서 개별적으로 사용하던 연동 규격은 자동으로 리다이렉트 처리됩니다. 따라서 기존에 판매중인 상품의 경우, 별도로 추가 개발을 할 필요가 없습니다.

기존규격	리 다이랙트	신규규격

레퍼러(referrer) 지원 (트래킹툴 지원)

intent를 통해 광고 성과를 포함한 각종 통계 수집이 필요한 경우 URL scheme에 referrer 파라미터가 추가되면 됩니다. AdBrix, TUNE, Adjust, AppsFlyer를 포함한 모든 트래킹툴에서 발행되는 measurement URL을 지원하므로 편리하게 마케팅 성과 측정이 가능합니다.

규격

onestore://common/product/{상품PID}?referrer=(STRING) 

또는

https://onesto.re/{상품PID}?referrer=(STRING) 

샘플

onestore://common/product/0000652407?referrer=com.square_enix.android.finalfantasy_sp%26ck%3d5416300%26sn%3d17866395096%26cid%3d961204606_17866395096

또는 

https://onesto.re/0000652407?referrer=com.square_enix.android.finalfantasy_sp%26ck%3d5416300%26sn%3d17866395096%26cid%3d961204606_17866395096

광고 성과 측정을 위해 트래킹 툴에서 measurement URL을 발급하려는 경우에도 원스토어 랜딩 URL (onestore:// 또는 https://onesto.re 규격) 사용이 가능합니다. 진행하려는 광고 성격에 따라 앱/게임 내부 광고인 경우 onestore:// 랜딩 URL 사용을 권장하며, 외부 매체(광고 네트웍, DSP 등)을 통한 광고 집행인 경우 https://onesto.re 랜딩 URL 사용을 권장합니다.

광고를 클릭하고 원스토어 상품 페이지로 진입하여 앱/게임을 설치한 경우, 트래킹 툴에서 발급한 measurement URL안에 들어있는 referrer를 원스토어가 다시 브로드캐스트합니다. 최대 60일까지의 look-back window가 지원되므로 진행하려는 마케팅 목적에 맞게 트래킹 툴에서 적절히 look-back window를 설정하고 진행하면 됩니다.

모바일 웹페이지에서 URL scheme 호출

html hyperlink reference로 위에서 정의된 custom url을 입력합니다. 사용자가 해당 link 선택시 아래와 같이 분기할 수 있도록 html page를 구성합니다.

앱 미설치 시 처리 방법 구현

앱이 있을 때는 바로 실행 가능하지만, 없을 때는 javascript timer를 사용해 setTimeout이 발생하는 경우, 모바일 웹 페이지나 구글플레이 등 다른 스토어로 분기시키는 방법을 사용합니다. (앱 미설치시, 페이지 이동 전에 잠시 오류 팝업이 보일 수 있습니다.) 아래는 스크립트 구성 예 입니다.

시스템 에러 메시지를 숨기기 위한 iframe 처리 등이 필요할 수 있습니다. intent scheme을 이용하면 좀 더 단순한 처리가 가능합니다.

var url = "onestore://common/product/0000252337?view_type=1"; 
var ONEstoreUrl = "https://onesto.re/0000252337" 

function onClickApp(url) { 
    var clickedAt = +new Date; 
                                               
    AppCheckTimer = setTimeout(function() { 
    if (+new Date - clickedAt < 2000){ 
        if (window.confirm("원스토어 최신 버전이 설치되어 있지 않습니다. \n모바일웹 페이지로 이동합니다.")) 
        { location.href = ONEstoreUrl; } 
            }
    }, 1500);
}
    location.href = url; 

Server side API

packageName 으로 PID 및 버전명 확인하기

이미 상품을 출시한 상태라면 패키지네임 openAPI를 통해서 PID와 각종 를 확인할 수 있습니다.

상세 내용은 레퍼런스를 참고한다.

Request 규격

http://m.onestore.co.kr/mobilepoc/api/getAppVersion.omp?pkgNm={패키지네임}&deviceModelCd={모델명}&osVer={OS버전}

Request 샘플

http://m.onestore.co.kr/mobilepoc/api/getAppVersion.omp?pkgNm=com.nhn.android.search&deviceModelCd=SM-N920S&osVer=6.0

Response 샘플

{
    "menuId": "DP04202",
    "game": false,
    "result": {
        "desc": "success",
        "code": "000"
    },
    "verNm": "",
    "verCd": "",
    "topMenuId": "DP30",
    "topMenuNm": "앱",
    "menuNm": "정보/상식",
    "sellerNm": "NAVER Corp.",
    "prodId": "0000030320",
    "title": "네이버 - NAVER"
}