연동규격 개발 가이드

개요

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

  규격

  onestore://common/product/{PID}

  샘플

  onestore://common/product/0000252337

• 검색호출

  • 검색뷰는 원스토어 앱이 해당 검색어에 대한 검색결과 화면을 보여주게 합니다.

    규격

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

    샘플

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

• 업데이트 요청

  • 앱/게임의 업데이트 요청을 받아, 해당 상품이 최신 버전이 아닌 경우 자동으로 업데이트 버전을 다운로드하고 설치합니다. 업데이트 요청을 하는 상품의 패키지 네임과 다운로드 할 상품의 패키지 네임이 동일한 경우에 동작합니다. 업데이트를 수행하기 위해서 다음과 같은 조건이 충족되어야 합니다.

    • 로그인 계정 내 구매 내역이 존재해야 합니다.

    • 구 버전의 상품이 설치되어 있어야 합니다.

    규격

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

    샘플

    onestore://common/product/bg_update/0000252337

Shorten URL로 연동하기

• PID를 활용해서 간단하게 앱 상세페이지 연동 주소를 생성할 수 있습니다. 원스토어 앱이 설치되어 있는 경우에는 앱 내 상세 페이지로 이동하며, 그렇지 않은 경우에는 원스토어 웹(m.onestore.net) 내 상세 페이지로 이동합니다.

  규격

  https://onesto.re/{PID}

  샘플

  https://onesto.re/0000252337

  기존 규격의 Redirects 처리

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

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

Server side API

• 패키지 네임으로 PID 및 버전 확인하기

  • 이미 상품을 출시한 상태라면 해당 API 를 통해 상품 정보를 확인할 수 있습니다.

    Request 규격

    GET https://oneapi.onestore.net/api/devcenter/getAppVersion/v1?pkgNm={패키지 네임}&deviceModelCd={모델명}&osVer={OS버전}&sdkVersion={SDK버전}

    Request 샘플

    https://oneapi.onestore.net/api/devcenter/getAppVersion/v1?pkgNm=com.nexon.bluearchiveone&deviceModelCd=SM-N960N&osVer=11.0&sdkVersion=30

    Response 샘플

    {
        "result": {
            "code": "000",
            "desc": "success"
        },
        "prodId": "0000758646",
        "verNm": "1.36.120365",
        "verCd": "120365",
        "title": "블루 아카이브",
        "topMenuId": "DP01",
        "topMenuNm": "게임",
        "menuId": "DP01004",
        "menuNm": "롤플레잉",
        "sellerNm": "(주) 넥슨",
        "game": true
    }

  • API 사용 시 유의사항

    • 해당 API는 GET 방식으로 호출해야합니다.

    • Android 개발자 문서의 Activity LifeCycle을 참고하여, App이 최초로 실행될 때(onCreate 시)에만 패키지 네임으로 PID 및 버전 확인하기 API를 호출할 수 있도록 개발해 주시기 바랍니다.

      • Activity LifeCycle

        • https://developer.android.com/reference/android/app/Activity#ActivityLifecycle

    • deviceModelCd를 입력한 경우 osVer도 반드시 입력해주세요.