21. 카카오톡 친구 초대 (3.12.0 미만)

Owned by kate.psy (Unlicensed)
Last updated: 4월 14, 2022 by KG_SDKDEV
3 min read

게임에서 카카오톡 친구 초대 기능을 연동하는 방법을 안내합니다.

 

 

 

카카오톡 친구 초대란?

 

카카오톡 친구 목록

  • 사용자의 카카오톡 친구에게 카카오톡 메시지를 전송하기 위해서는 친구 목록을 불러와야 합니다.

    • 게임에 가입한 친구를 가져오는 API와 미가입 친구를 가져오는 API가 분리되어 있습니다. 용도에 맞게 사용해주세요.

    • 친구 목록은 닉네임 순으로 정렬되어 내려옵니다.

  • 친구 목록은 서버에서 캐싱하도록 되어 있습니다.

    • 서버의 캐시 만료 시간은 10분이나, API 정책에 따라 바뀔 수 있음을 양해 부탁드립니다.

  • 게임에 미가입 친구 목록 조회는 "21.1.2. 카카오톡 초대 가능한 추천 친구 목록 조회하기" 문서를 참고하시기 바랍니다.

 

카카오톡 초대 메시지

  • 카카오톡 초대 메시지는 카카오톡 초대 대상자에게만 전송이 가능합니다.

  • [카카오 개발자 사이트 - 메시지 템플릿 V2] 메뉴에서 메시지 템플릿을 등록해야 메시지를 보낼 수 있습니다.

    • 가이드 : 20. 카카오톡 메시지 템플릿 V2

    • 메시지 템플릿은 용도에 따라 각각 생성하셔야 합니다.

    • 템플릿에 태그를 넣고, 클라이언트에서 치환해서 문구를 동적으로 보낼 수 있습니다. 주의해 주세요!!!

    • 발신자의 닉네임을 포함할 경우, 반드시 유저의 카카오톡 프로필의 닉네임으로 전송해주셔야 최신의 카카오톡 닉네임으로 전송됩니다. 

카카오톡 초대 메시지 보내기 구현시 유의사항

  •  메시지 전송 시, 상대방의 talkOs(카카오톡에 가입된 기기의 OS 정보) 값을 참고해서 구현해주세요.

    • talkOs는 "android" 혹은 "ios" 라는 String 값을 가집니다.

    • 메시지를 받을 친구가 게임에서 지원하지 않는 OS를 사용하는 경우 초대 메시지를 호출하지 않도록 구현해주세요.

    • 전송 시, 목록에서 얻은 친구 정보를 그대로 사용하여 전송해주세요.

  • 현재 지원중인 OS의 정보는 서버에 저장하시길 권장합니다.

    • 서버에 현재 지원중인 OS 정보를 저장하시고, 해당 값과 비교하도록 구현해주세요.

    • 클라이언트에서 저장할 경우, 후발 OS 버전의 게임이 출시될 때 이미 출시된 OS 버전의 클라이언트 또한 업데이트해야 정상적으로 초대메시지를 보낼 수 있습니다.

    • 예를 들어, AOS 버전의 게임을 우선 서비스하다가 iOS 버전의 게임을 출시할 때, AOS 버전의 클라이언트에도 지원 OS에 "ios"를 추가해주어야 메시지를 정상적으로 보낼 수 있으므로, AOS 버전 또한 업데이트해야만 하는 일이 발생할 수 있습니다.

  • ErrorCode 로 처리하지 말아주세요

    • talkOs를 참조하는 방식이 아닌, 초대 메시지를 보내고 ErrorCode 를 받아 처리할 경우, OS간 출시일에 차이가 있으면 아직 출시하지 않은 OS 사용자에게 메시지가 갈 수 있으니 주의해주세요.

  • 한 친구에게는 한달에 1번만 초대 메시지 전송이 가능합니다.

    • 초대 메시지를 보내고 한달이 지나지 않은 상태에서 다시 초대 메시지를 보낼 경우 에러가 리턴됩니다.

    • 게임을 실행 전 유저는 playerId가 없는 상태이기 때문에 KGKakaoProfile.getUUID() 를 이용하여 게임에서 관리하여 사용 가능합니다.

      • serviceUserId는 deprecated 되었습니다. 해당 값이 없는 유저가 내려올 수 있으므로 신규 게임에서는 사용하지 마세요.

 

초대 받은 유저가 게임에 신규 가입 시, 초대자와 가입자에게 보상 지급

  • 해당 기능은 카카오게임즈 사업PM과 사전 협의 완료 후, 진행 가능합니다.

  • 초대자가 게임에 미가입한 카카오톡 친구에게 초대메시지를 발송한 후, 수신자가 유저가 게임에 가입하면 초대자와 가입자에게 보상을 지급할 수 있습니다.

  • 다음과 같이 사전에 설정되어야 동작합니다.

    1. [3.0 플랫폼 어드민 - 프로모션 - 카카오톡 친구초대] 메뉴에서 이벤트를 등록합니다.

    2. 이벤트 등록 단계에서 초대자와 가입자에게 각각 지급하는 보상을 다르게 정의하여 지급할 수 있습니다.

    3. [카카오 개발자 사이트 - 메시지 템플릿 V2] 메뉴에서 초대메시지 템플릿을 등록합니다.

  • 초대 가입 조건

    • 초대 이벤트 기간동안 초대받은 유저가 해당 게임에 최초로 가입 시, 초대 가입으로 인정됩니다. 

    • 이벤트 기간에 탈퇴 후 재가입한 경우는 제외됩니다.

  • 가입보상 지급 정책

    • 초대자 : 초대메시지를 발송한 후, 24시간 이내에 수신자가 게임에 최초 가입 시 보상이 지급됩니다.

      • 가입일 기준, 24시간 이내

        • 예) 초대받은 유저가 12월 3일 01시에 가입했다면, 12월 2일 01시 ~ 12월 3일 01시 사이에 초대메시지를 보낸 유저에게 보상이 지급됨

      • 가입자가 N명의 친구들에게 초대메시지를 수신한 후 가입을 했다면? 초대한 N명의 친구들에게 보상이 지급됩니다. 

    • 가입자 : 가입 즉시 보상이 지급됩니다.

  • 예시