콘텐츠로 이동

초대 코드 기반 매칭

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

Warning

아래 모든 API에서 Authorization Header는 필수가 아닙니다. 단, 보안을 위해 Hive 인증키를 사용하고 게임 서버에서 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

환경 URL
상용 https://promotion.qpyou.cn/ua/inviteCode/campaign
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign

요청 방식 및 데이터 형식

항목 설명
HTTP Method POST
Content-Type application/json
필드명 설명 타입 필수여부
Authorization Bearer 인증을 통한 certificationKey 유효성 판단 String N

Request Body

필드명 설명 타입 필수여부
gameindex 게임 고유 번호 Integer Y

호출 예제

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

API 응답 명세

Response

필드명 설명 타입 필수여부
result_code 응답 코드
  • 200: 성공
  • 그 외: 실패
Integer Y
result_message 응답 메시지 String Y
campaign_list 초대 코드 캠페인 리스트 Array Y
ㄴ id 프로모션 캠페인 ID Integer N
ㄴ title 캠페인 제목 String N
ㄴ rewards 보상 리스트 Array N
ㄴㄴ reward_id 보상 ID Integer N
ㄴㄴ description 보상 설명 String N
ㄴㄴ reward_type 보상 타입
  • action: 행동 보상
  • goal: 목표 수 달성 보상
String N
ㄴㄴ action_type 행동 타입
  • match: 매칭
  • cpi: 설치
  • cpa: 특정 행동 달성
String N
ㄴㄴ cpa_code cpa 고유 번호
  • 행동 타입이 cpa인 경우 유효한 값을 전달
  • cpa가 아닌 경우 Null로 전달
 Integer N
ㄴㄴ goal 목표 수 Integer N
ㄴㄴ limit 보상 제한 수 Integer N

응답 예제

{
    "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

환경 URL
상용 https://promotion.qpyou.cn/ua/inviteCode/getCode
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/getCode

요청 방식 및 데이터 형식

항목 설명
HTTP Method POST
Content-Type application/json

Header

필드명 설명 타입 필수여부
Authorization Bearer 인증을 통한 certificationKey 유효성 판단 String N

Request Body

필드명 설명 타입 필수여부
gameindex 게임 고유 번호 Integer Y
campaign_id 초대 코드 캠페인 고유 번호 Integer Y
player_id 모듈에 따라 vid 혹은 uid 중 1개 필요
- vid : 통합모듈인 경우 필수
- uid : 개별모듈인 경우 필수		 String Y
server_id 게임 서버 고유 ID String Y

호출 예제

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

필드명 설명 타입 필수여부
result_code 응답 코드
  • 200: 성공
  • 그 외: 실패
Integer Y
result_message 응답 메시지 String Y
invite_code 발급된 초대 코드 String Y

응답 예제

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

초대 코드 매칭하기

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

API 요청 명세

Request URL

환경 URL
상용 https://promotion.qpyou.cn/ua/inviteCode/companion
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/companion

요청 방식 및 데이터 형식

항목 설명
HTTP Method POST
Content-Type application/json

Header

필드명 설명 타입 필수여부
Authorization Bearer 인증을 통한 certificationKey 유효성 판단 String N

Request Body

필드명 설명 타입 필수여부
gameindex 게임 고유 번호 Integer Y
invite_code 발급된 초대 코드 String Y
player_id 모듈에 따라 vid 혹은 uid 중 1개 필요
- vid : 통합모듈인 경우 필수
- uid : 개별모듈인 경우 필수		 String Y
server_id 게임 서버 고유 ID String Y

호출 예제

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

필드명 설명 타입 필수여부
result_code 응답 코드
  • 200: 성공
  • 그 외: 실패
Integer Y
result_message 응답 메시지 String Y
detail 발급된 초대 코드 Array Y
ㄴㄴmatched 매칭 여부 Boolean Y
ㄴㄴreason 매칭 실패 사유 String Y

응답 예제

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

보상 현황 확인 하기

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

API 요청 명세

Request URL

환경 URL
상용 https://promotion.qpyou.cn/ua/inviteCode/progress
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/progress

요청 방식 및 데이터 형식

항목 설명
HTTP Method POST
Content-Type application/json

Header

필드명 설명 타입 필수여부
Authorization Bearer 인증을 통한 certificationKey 유효성 판단 String N

Request Body

필드명 설명 타입 필수여부
gameindex 게임 고유 번호 Integer Y
invite_code 발급된 초대 코드 String Y

호출 예제

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

필드명 설명 타입 필수여부
result_code 응답 코드
  • 200: 성공
  • 그 외: 실패
Integer Y
result_message 응답 메시지 String Y
progress_list 보상 진행 현황 리스트(보상 진행 이력 없을 시, 빈 배열로 전달) Array Y
ㄴ reward_id 보상 ID Integer N
ㄴ reward_type 보상 타입
  • action: 행동 보상
  • goal: 목표 수 달성 보상
String N
ㄴ action_type 행동 타입
  • match: 매칭
  • cpi: 설치
  • cpa: 특정 행동 달성
String N
ㄴ count 보상 지급 수 Integer N
ㄴ max_reward 최대 보상 제한 수 Integer N
ㄴ goal_progress 목표 달성 현황
  • 보상 타입이 '목표 수 달성 보상'일때 사용
  • 목표 수(goal) 만큼 달성 시 보상 지급
Integer N
ㄴ goal 목표 수
  • 보상 타입이 '목표 수 달성 보상'일때 사용
Integer N
ㄴ goal_achieved 목표 달성 수
  • 보상 타입이 '목표 수 달성 보상'일때 사용
Integer N

응답 예제

{
  "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"
}