초대 코드 기반 매칭¶

유저 초대는 유저가 초대 코드를 발급하여 다른 유저를 게임으로 초대하고, 개발사로부터 이에 대한 보상을 받는 기능입니다. 사용자 초대 API는 게임에서 초대 코드를 발급받아 초대를 수락한 사용자를 매칭할 수 있는 API입니다.

사용 방법¶

1. Hive 콘솔 > 프로모션 > 유저 초대 > 초대 캠페인 등록에서 초대 코드 발급 타입으로 캠페인을 생성합니다.
2. 초대 캠페인 정보를 조회해 유효한 캠페인 ID를 게임 서버에 저장합니다.
3. 유저 초대 페이지에서 입력받은 초대자 정보, 위에서 저장한 캠페인 ID를 호출 파라미터로 전달하고 초대 코드를 발급받습니다.
4. 초대 수락자 정보(player_id 등)와 수락자가 받은 초대 코드를 호출 파라미터로 전달하고 매칭 요청을 합니다.
5. 보상 현황 확인 하기를 호출해 유저 초대 페이지에 보상을 받기 위한 진행 상황을 표시합니다.

사전 준비¶

초대 코드 관련 API를 사용하려면 다음 항목을 준비해야 합니다.

• Authorization Header에 사용할 Hive 인증키: Hive 콘솔 > 앱센터 > 프로젝트 관리 > 앱 검색 후 앱 선택 > 게임 상세 > 기본정보 > Hive 인증키
• server_id: Hive 콘솔 > 앱센터 > 프로젝트 관리 > 앱 검색 후 앱 선택 > 게임 상세 > 게임 서버
• 초대 캠페인: Hive 콘솔 > 프로모션 > 유저 초대 > 초대 캠페인 등록에서 초대 코드 발급 타입으로 캠페인을 생성

캠페인 정보 조회하기¶

Hive 콘솔에서 생성한 초대 캠페인 정보를 조회합니다. 활성화되고 사용 가능한 초대 캠페인 정보만 불러옵니다. 응답값으로 캠페인 내 설정된 보상 정보도 같이 전달합니다.

API 요청 명세¶

Request URL¶

요청 방식 및 데이터 형식¶

Header¶

Request Body¶

호출 예제¶

curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign" \
        -H "Content-Type: application/json" \
        -d '{
        "gameindex": 539
        }'

API 응답 명세¶

Response¶

응답 예제¶

{
    "campaign_list": [
    {
        "id": "19",
            "title": "초대 코드 발급_행동_설치(초대 2, 수락 3, 제한 2)",
            "rewards": [
        {
            "reward_id": 33,
                "description": "행동_설치(초대 2, 수락 3, 제한 2)",
                "reward_type": "action",
                "action_type": "cpi",
                "cpa_code": null,
                "goal": 1,
                "limit": 2
        }
      ]
    }
  ],
    "result_code": 200,
    "result_message": "Success"
}

초대 코드 발급 받기¶

사용자는 캠페인에서 초대 코드를 발급받을 수 있습니다. 각 캠페인은 하나의 초대 코드만 발급할 수 있습니다. 초대자에게 보상을 지급하려면 초대자가 접속한 서버 ID를 전달해야 합니다.

API 요청 명세¶

Request URL¶

요청 방식 및 데이터 형식¶

Header¶

Request Body¶

호출 예제¶

curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/getCode" \
    -H "Content-Type: application/json" \
    -d '{
          "gameindex" : 539,
          "campaign_id": 19,
          "player_id" : 12341234,
          "server_id" : "kr"
        }'

API 응답 명세¶

Response¶

응답 예제¶

{
  "invite_code": "ESOJ0TOC",
  "result_code": 200,
  "result_message": "Success"
}

초대 코드 매칭하기¶

초대 코드를 입력하여 초대자와 수신자를 매칭합니다. 보상 어뷰징을 방지하려면, 매칭 요청 전에 게임 서버에서 수락자 계정 정보가 유효한지 검증 후 요청하는 것을 권장합니다. 매칭 보상은 캠페인별로 최초 1회만 지급합니다.

API 요청 명세¶

Request URL¶

요청 방식 및 데이터 형식¶

Header¶

Request Body¶

호출 예제¶

curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/companion" \
    -H "Content-Type: application/json" \
    -d '{
          "gameindex" : 539,
          "invite_code" :"ESOJ0TOC",
          "player_id" : 234234,
          "server_id" : "kr"
        }'

API 응답 명세¶

Response¶

응답 예제¶

{
  "detail": {
    "matched": true,
    "reason": "Both matching and rewards were successful"
  },
  "result_code": 200,
  "result_message": "Success"
}

보상 현황 확인 하기¶

초대 코드의 보상 현황을 조회합니다.

API 요청 명세¶

Request URL¶

요청 방식 및 데이터 형식¶

Header¶

Request Body¶

호출 예제¶

curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/progress" \
        -H "Content-Type: application/json" \
        -d '{
          "gameindex" : 539,
          "invite_code" :"ESOJ0TOC"
        }'

API 응답 명세¶

Response¶

응답 예제¶

{
  "progress_list": [
    {
      "reward_id": 19,
      "reward_type": "action",
      "action_type": "match",
      "count": 1,
      "max_reward": 1,
      "goal_progress": 0,
      "goal_achieved": 0
    },
    {
      "reward_id": 20,
      "reward_type": "goal",
      "action_type": "cpi",
      "count": 2,
      "max_reward": 2,
      "goal_progress": 1,
      "goal": 3,
      "goal_achieved": 2
    }
  ],
  "result_code": 200,
  "result_message": "Success"
}