21. 카카오톡 친구 초대 (3.12.0 미만)
게임에서 카카오톡 친구 초대 기능을 연동하는 방법을 안내합니다.
카카오톡 친구 초대란?
카카오톡 친구인데, 해당 게임에 미가입한 유저에서 초대 메시지를 발송하여 가입을 유도할 수 있습니다.
친구 초대 시, 초대자에게 보상을 지급할 수 있습니다.
SDK API를 연동하여 친구목록 조회 후 초대메시지 발송할 수 있고, 초대 보상 지급은 게임에서 구현할 수 있습니다.
초대 받은 유저가 게임에 신규 가입하면, 초대자와 가입자에게 보상을 지급할 수 있습니다.
SDK API 연동 및 플랫폼 어드민에서 이벤트 등록/보상 설정하여, 가입에 대한 보상을 초대자와 가입자에게 지급할 수 있습니다.
카카오톡 친구초대 이벤트 생성은 <https://kakaogames.atlassian.net/wiki/spaces/KS3GFC/pages/413468240 > 가이드를 참고해 주세요.
예시
카카오톡 친구 목록
사용자의 카카오톡 친구에게 카카오톡 메시지를 전송하기 위해서는 친구 목록을 불러와야 합니다.
게임에 가입한 친구를 가져오는 API와 미가입 친구를 가져오는 API가 분리되어 있습니다. 용도에 맞게 사용해주세요.
친구 목록은 닉네임 순으로 정렬되어 내려옵니다.
친구 목록은 서버에서 캐싱하도록 되어 있습니다.
서버의 캐시 만료 시간은 10분이나, API 정책에 따라 바뀔 수 있음을 양해 부탁드립니다.
게임에 미가입 친구 목록 조회는 "21.1.2. 카카오톡 초대 가능한 추천 친구 목록 조회하기" 문서를 참고하시기 바랍니다.
카카오톡 초대 메시지
카카오톡 초대 메시지는 카카오톡 초대 대상자에게만 전송이 가능합니다.
[카카오 개발자 사이트 - 메시지 템플릿 V2] 메뉴에서 메시지 템플릿을 등록해야 메시지를 보낼 수 있습니다.
가이드 : https://kakaogames.atlassian.net/wiki/spaces/KS3GFC/pages/413468185
메시지 템플릿은 용도에 따라 각각 생성하셔야 합니다.
템플릿에 태그를 넣고, 클라이언트에서 치환해서 문구를 동적으로 보낼 수 있습니다. 주의해 주세요!!!
발신자의 닉네임을 포함할 경우, 반드시 유저의 카카오톡 프로필의 닉네임으로 전송해주셔야 최신의 카카오톡 닉네임으로 전송됩니다.
카카오톡 초대 메시지 보내기 구현시 유의사항
메시지 전송 시, 상대방의 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과 사전 협의 완료 후, 진행 가능합니다.
초대자가 게임에 미가입한 카카오톡 친구에게 초대메시지를 발송한 후, 수신자가 유저가 게임에 가입하면 초대자와 가입자에게 보상을 지급할 수 있습니다.
다음과 같이 사전에 설정되어야 동작합니다.
[3.0 플랫폼 어드민 - 프로모션 - 카카오톡 친구초대] 메뉴에서 이벤트를 등록합니다.
이벤트 등록 단계에서 초대자와 가입자에게 각각 지급하는 보상을 다르게 정의하여 지급할 수 있습니다.
[카카오 개발자 사이트 - 메시지 템플릿 V2] 메뉴에서 초대메시지 템플릿을 등록합니다.
초대 가입 조건
초대 이벤트 기간동안 초대받은 유저가 해당 게임에 최초로 가입 시, 초대 가입으로 인정됩니다.
이벤트 기간에 탈퇴 후 재가입한 경우는 제외됩니다.
가입보상 지급 정책
초대자 : 초대메시지를 발송한 후, 24시간 이내에 수신자가 게임에 최초 가입 시 보상이 지급됩니다.
가입일 기준, 24시간 이내
예) 초대받은 유저가 12월 3일 01시에 가입했다면, 12월 2일 01시 ~ 12월 3일 01시 사이에 초대메시지를 보낸 유저에게 보상이 지급됨
가입자가 N명의 친구들에게 초대메시지를 수신한 후 가입을 했다면? 초대한 N명의 친구들에게 보상이 지급됩니다.
가입자 : 가입 즉시 보상이 지급됩니다.
예시
