21.1. KakaoTalk Invitation SDK Example
Do not mix with existing APIs under 3.9.0.
21.1.1. Querying ongoing invitation event list
This section shows an example of a query of the ongoing invitation event list.
Unity 예제
using KakaoGame.SDK; using KakaoGame.SDK.Kakao; // query of the ongoing invitation event list. KGKakaoInvitation.LoadEvents((result, events) => { if (result.isSuccess) { // Successful invitation event list lookup if (events != nil) { foreach (KGKakaoEvent invitationEvent in invitationEvents) { // Event ID: Required when sending an invitation message, to retrieve a list of invitees or senders. int eventId = invitationEvent.eventId; // Event start time long startTime = invitationEvent.startTime; // Event end time long finishTime = invitationEvent.finishTime; // Event Description string eventDescription = invitationEvent.eventDescription; } } } else if (result.code == KGResultCode.NotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail invitation event list lookup } }); |
Android 예제
import com.kakaogame.KGKakaoInvitation; import com.kakaogame.KGKakaoInvitation.KGKakaoEvent; import com.kakaogame.KGResult; // query of the ongoing invitation event list. KGKakaoInvitation.loadEvents(new KGResultCallback<List<KGKakaoEvent>>() { @Override public void onResult(KGResult<List<KGKakaoEvent>> result) { if (result.isSuccess()) { // Successful invitation event list lookup List<KGKakaoEvent> invitationEventList = result.getContent(); for (KGKakaoEvent invitationEvent : invitationEventList) { // Event ID: Required when sending an invitation message, to retrieve a list of invitees or senders. int eventId = invitationEvent.getEventId(); // Event start time long startTime = invitationEvent.getStartTime(); // Event end time long finishTime = invitationEvent.getFinishTime(); // Event Description String description = invitationEvent.getEventDescription(); } } else if (result.getCode() == KGResult.KGResultCode.NOT_KAKAOTALK_USER) { // The user is not a KakaoTalk user. } else { // Fail invitation event list lookup } } }); |
iOS 예제
#import <KakaoGame/KakaoGame.h> // query of the ongoing invitation event list. [KGKakaoInvitation loadEventsWithCompletionHandler:^(NSError *error, NSArray *invitationEvents) { if (IS_SUCCESS(error) == YES) { // Successful invitation event list lookup if (invitationEvents != nil) { for (KGKakaoEvent *invitationEvent in invitationEvents) { // Event ID: Required when sending an invitation message, to retrieve a list of invitees or senders. int eventId = invitationEvent.eventId; // Event start time long long startTime = invitationEvent.startTime; // Event end time long long finishTime = invitationEvent.finishTime; // Event Description NSString *eventDescription = invitationEvent.eventDescription; } } } else if (error.code == KGErrorNotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail invitation event list lookup } }]; |
21.1.2. Querying KakaoTalk Invitation Target List
This section shows an example of a query of the KakaoTalk invitation target list.
KakaoGame Platform will recommended friends who will join the game with high possibility. The number of recommended friends may less than the number of recommend limt you have set.
When sending an invitation message to KakaoTalk, you must pass the 'KakaoProfile' object received using this API as an argument.
The friend list is first listed according to the ranking given by the server on the recommend limit, and then sorted in alphabetical order.
If you want to show recommended friends in the UI, you can use the 'isRecommended' argument.
Unity 예제
using Kakaogame.SDK; using Kakaogame.SDK.Kakao; // [TODO] Set limit of recommended friends int recommendLimit = 5; // The number of recommended friends // int recommendLimit = 0; // Set to 0 if you want to fetch the list without recommended friends // int recommendLimit = -1; // Set it to -1 if you want to include all of your recommended friends (the number of recommended friends is variably) // [TODO] Set start value for querying friend list int offset; // Start value for querying friend list // [TODO] Set size of querying friend list int limit; // Friend list size // Querying KakaoTalk Invitation Target List KGKakaoInvitation.LoadInvitableFriendProfiles(recommendLimit, offset, limit, (result, totalCount, kakaoProfiles) => { if (result.isSuccess) { // Success // Query of invitation target friend profile list successful foreach (KGKakaoProfile kakaoProfile in kakaoProfiles) { // KakaoTalk nickname string nickname = kakaoProfile.nickname; // KakaoTalk profile thumbnail image url string thumbnailImageUrl = kakaoProfile.thumbnailImageUrl; // If this user is a recommended friend or not BOOL isRecommended = kakaoProfile.isRecommended; // KakaoTalk installation os string talkOs = kakaoProfile.kakaoTalkOS.ToString(); // Whether your friends are allowed to get messages or not. You must not send message if it is 'false'. bool isAllowMessage = kakaoProfile.isAllowedMessage; } } else if (result.code == KGResultCode.NotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail... } }); |
Android 예제
import com.kakaogame.KGKakaoInvitation; import com.kakaogame.KGKakaoProfile; import com.kakaogame.KGKakaoProfile.KGKakaoFriendsResponse; import com.kakaogame.KGResult; // [TODO] Set limit of recommended friends int recommendLimit = 5; // The number of recommended friends // int recommendLimit = 0; // Set to 0 if you want to fetch the list without recommended friends // int recommendLimit = -1; // Set it to -1 if you want to include all of your recommended friends (the number of recommended friends is variably) // [TODO] Set start value for querying friend list int offset; // Start value for querying friend list // [TODO] Set size of querying friend list int limit; // Friend list size // Querying KakaoTalk Invitation Target List KGKakaoInvitation.loadInvitableFriendProfiles(recommendLimit, offset, limit, new KGResultCallback<KGKakaoFriendsResponse>() { @Override public void onResult(KGResult<KGKakaoFriendsResponse> result) { if (result.isSuccess()) { // Success // Query of invitation target friend profile list successful KGKakaoFriendsResponse response = result.getContent(); // Total count of friends you can invite int totalCount = response.getTotalCount(); // Invite Friend List - list of friend profile objects to use when sending invitation messages List<KGKakaoProfile> friendList = response.getFriendList(); for (KGKakaoProfile kakaoProfile : friendList) { // KakaoTalk nickname String nickname = kakaoProfile.getNickname(); // KakaoTalk profile thumbnail image url String thumbnailImageUrl = kakaoProfile.getThumbnailImageUrl(); // If this user is a recommended friend or not boolean isRecommended = kakaoProfile.isRecommended(); // KakaoTalk installation os String talkOs = kakaoProfile.getTalkOs(); // Whether your friends are allowed to get messages or not. You must not send message if it is 'false'. boolean isAllowMessage = kakaoProfile.isAllowedMessage(); } } else if (result.getCode() == KGResult.KGResultCode.NOT_KAKAOTALK_USER) { // The user is not a KakaoTalk user. } else { // Fail... } } }); |
iOS 예제
#import <KakaoGame/KakaoGame.h> // [TODO] Set limit of recommended friends int recommendLimit = 5; // The number of recommended friends // int recommendLimit = 0; // Set to 0 if you want to fetch the list without recommended friends // int recommendLimit = -1; // Set it to -1 if you want to include all of your recommended friends (the number of recommended friends is variably) // [TODO] Set start value for querying friend list int offset; // Start value for querying friend list // [TODO] Set size of querying friend list int limit; // Friend list size // Querying KakaoTalk Invitation Target List [KGKakaoInvitation loadInvitableFriendProfilesWithRecommendLimit:recommendLimit offset:offset limit:limit completionHandler:^(NSError *error, int totalCount, NSArray *idpProfiles) { if (IS_SUCCESS(error) == YES) { // Success // Query of invitation target friend profile list successful for (KGKakaoProfile *kakaoProfile in idpProfiles) { // KakaoTalk nickname NSString *nickname = kakaoProfile.nickname; // KakaoTalk profile thumbnail image url NSString *thumbnailImageUrl = kakaoProfile.thumbnailImageUrl; // If this user is a recommended friend or not BOOL isRecommended = kakaoProfile.isRecommended; // KakaoTalk installation os NSString *talkOs = kakaoProfile.kakaoTalkOS.description; // Whether your friends are allowed to get messages or not. You must not send message if it is 'false'. BOOL isAllowMessage = kakaoProfile.isAllowedMessage; } } else if (error.code == KGErrorNotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail... } }]; |
21.1.3. Sending a KakaoTalk Invitation Message
This section shows an example of KakaoTalk invitation message sending. (Guide :20. Kakaotalk Message Template V2 )
Unity 예제
using Kakaogame.SDK; using Kakaogame.SDK.Kakao; // [TODO] Set event Id int eventId = 511; // Send the invitation message for this event // [TODO] Set invitation message template ID int templateId = 4100; // The Id value of the template created by the Message Template Admin // [TODO] Add required arguments to invitation message String nickname = ((KGKakaoProfile) KGLocalPlayer.getCurrentPlayer().getIdpProfile()).getNickname(); Map<String, String> args = new LinkedHashMap<String, String>(); args.put("${sender_name}", nickname); // [TODO] Set up recipient profiles KGKakaoProfile kakaoProfile; // The profile object looked up by 'loadInvitableFriendProfiles' // Send a Kakaotalk invitation message KGKakaoInvitation.SendInviteMessage(eventId, kakaoProfile, templateId, args, (result) => { if (result.isSuccess) { // Success } else { // Failed to send Kakao Talk invitation message if (result.code == KGResultCode.MessageSettingDisabled) { // If the recipient has opted-out of the message } else if (result.code == KGResultCode.ExceedDailyUsage) { // Occurs when there is a day's quota (regardless of recipient) that one person can send for a particular app } else if (result.code == KGResultCode.ExceedMonthlyUsage) { // Occurs when one month exceeds a month's quota that a specific person can send to a particular app } else if (result.code == KGResultCode.NotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Other errors... } } }); |
Android 예제
import com.kakaogame.KGKakaoInvitation; import com.kakaogame.KGLocalPlayer; import com.kakaogame.KGKakaoProfile; import com.kakaogame.KGResult; // [TODO] Set event Id int eventId = 511; // Send the invitation message for this event // [TODO] Set invitation message template ID int templateId = 4100; // The Id value of the template created by the Message Template Admin // [TODO] Add required arguments to invitation message string nickname = ((KGKakaoProfile) KGLocalPlayer.currentPlayer.idpProfile).nickname; Dictionary<String, String> args = new Dictionary<String, String>(); args.add("${sender_name}", nickname); // [TODO] Set up recipient profiles KGKakaoProfile kakaoProfile; // The profile object looked up by 'loadInvitableFriendProfiles' // Send a Kakaotalk invitation message KGKakaoInvitation.sendInviteMessage(eventId, kakaoProfile, templateId, args, new KGResultCallback<Void>() { @Override public void onResult(KGResult<Void> result) { if (result.isSuccess()) { // Success } else { // Failed to send Kakao Talk invitation message if (result.getCode() == KGResult.KGResultCode.MESSAGE_SETTING_DISABLE) { // If the recipient has opted-out of the message } else if (result.getCode() == KGResult.KGResultCode.EXCEED_DAILY_USAGE) { // Occurs when there is a day's quota (regardless of recipient) that one person can send for a particular app } else if (result.getCode() == KGResult.KGResultCode.EXCEED_MONTHLY_USAGE) { // Occurs when one month exceeds a month's quota that a specific person can send to a particular app } else if (result.getCode() == KGResult.KGResultCode.NOT_KAKAOTALK_USER) { // The user is not a KakaoTalk user. } else { // Other errors... } } } }); |
iOS 예제
#import <KakaoGame/KakaoGame.h> // [TODO] Set event Id int eventId = 511; // Send the invitation message for this event // [TODO] Set invitation message template ID int templateId = 4100; // The Id value of the template created by the Message Template Admin // [TODO] Add required arguments to invitation message String nickname = ((KGKakaoProfile) KGLocalPlayer.getCurrentPlayer().getIdpProfile()).getNickname(); Map<String, String> args = new LinkedHashMap<String, String>(); args.put("${sender_name}", nickname); // [TODO] Set up recipient profiles KGKakaoProfile kakaoProfile; // The profile object looked up by 'loadInvitableFriendProfiles' // Send a Kakaotalk invitation message [KGKakaoInvitation sendInviteMessageWithEventId:eventId kakaoProfile:kakaoProfile templateId:templateId argumentDic:args (result) => { if (IS_SUCCESS(error) == YES) { // Success } else if (error.code == KGErrorMessageSettingDisabled) { // If the recipient has opted-out of the message } else if (error.code == KGErrorExceedDailyUsage) { // Occurs when there is a day's quota (regardless of recipient) that one person can send for a particular app } else if (error.code == KGErrorExceedMothlyUsage) { // Occurs when one month exceeds a month's quota that a specific person can send to a particular app } else if (error.code == KGErrorNotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Failed to send Kakao Talk invitation message } }]; |
21.1.4. Querying the number of friends I sent an invitation to
This section shows an example of a query of the count of friends who have received my invitation.
Unity 예제
using KakaoGame.SDK; using KakaoGame.SDK.Kakao; // [TODO] Set event Id int eventId = 511; // Querying this invitation event KGKakaoInvitation.LoadReceiversCount(eventId, (result, totalReceiversCount, joinersCount) => { if (result.isSuccess) { // Success // Total receivers count int totalCount = totalReceiversCount; // Number of friends who joined the game int registeredCount = joinersCount; } else { // Fail... } }); |
Android 예제
import com.kakaogame.KGKakaoInvitation; import com.kakaogame.KGKakaoInvitation.KGInvitationReceviersResponse; import com.kakaogame.KGPlayer; import com.kakaogame.KGKakaoProfile; import com.kakaogame.KGResult; // [TODO] Set event Id int eventId = 511; // Querying this invitation event // Querying the number of friends I sent an invitation to KGKakaoInvitation.loadReceiversCount(eventId, new KGResultCallback<KGInvitationReceviersCountResponse>() { @Override public void onResult(KGResult<KGInvitationReceviersCountResponse> result) { if (result.isSuccess()) { // Success KGInvitationReceviersCountResponse response = result.getContent(); // Total receivers count int total = response.getTotalReceiversCount(); // Number of friends who joined the game int joinersCount = response.getJoinersCount(); } else { // Fail... } } }); |
iOS 예제
#import <KakaoGame/KakaoGame.h> // [TODO] Set event Id int eventId = 511; // Querying this invitation event [KGKakaoInvitation loadReceiversCountWithEventId:eventId completionHandler:^(NSError *error, int totalReceiversCount, int joinersCount) { if (IS_SUCCESS(error) == YES) { // Success // Total receivers count int totalCount = totalReceiversCount; // Number of friends who joined the game int registeredCount = joinersCount; } else { // Fail... } }]; |
21.1.5. Querying the list of friends I sent an invitation to
This section shows an example of a query of the list of friends who have received my invitation.
Unity 예제
using KakaoGame.SDK; using KakaoGame.SDK.Kakao; // [TODO] Set event Id int eventId = 511; // Querying this invitation event // Querying the list of friends I sent an invitation to KGKakaoInvitation.LoadReceivers(eventId, (result, joiners, invitees) => { if (result.isSuccess) { // Success // List of players joined to the app, including unlink users foreach (KGPlayer joiner in joiners) { // Receiver's playerId string playerId = joiner.playerId; KGKakaoProfile kakaoProfile = (KGKakaoProfile)joiner.idpProfile; // Receiver's nickname string nickname = kakaoProfile.nickname; // Receiver's KakaoTalk thumbnail profile image url string thumbnailImageUrl = kakaoProfile.thumbnailImageUrl; // If the player has unlinked this app or not // If you want to display information on whether or not to leave the UI, use this flag BOOL isUnregistered = kakaoProfile.isUnregistered; } // List of recipients who have not yet joined the app // Player ID is not provided because the user has not signed up for the app foreach (KGKakaoPrfoile invitee in invitees) { // Receiver's nickname string nickname = invitee.nickname; // Receiver's KakaoTalk thumbnail profile image url string thumbnailImageUrl = invitee.thumbnailImageUrl; } } else if (result.code == KGResultCode.NotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail... } }); |
Android 예제
import com.kakaogame.KGKakaoInvitation; import com.kakaogame.KGKakaoInvitation.KGInvitationReceviersResponse; import com.kakaogame.KGPlayer; import com.kakaogame.KGKakaoProfile; import com.kakaogame.KGResult; // [TODO] Set event Id int eventId = 511; // Querying this invitation event // Querying the list of friends I sent an invitation to KGKakaoInvitation.loadReceivers(eventId, new KGResultCallback<KGKakaoInvitation.KGInvitationReceviersResponse>() { @Override public void onResult(KGResult<KGKakaoInvitation.KGInvitationReceviersResponse> result) { if (result.isSuccess()) { // Success KGKakaoInvitation.KGInvitationReceviersResponse receivers = result.getContent(); // List of players joined to the app, including unlink users List<KGPlayer> joiners = receivers.getJoiners(); for (KGPlayer player : joiners) { // Receiver's playerId String playerId = player.getPlayerId(); KGKakaoProfile kakaoProfile = (KGKakaoProfile) player.getIdpProfile(); // Receiver's nickname String nickname = kakaoProfile.getNickname(); // Receiver's KakaoTalk thumbnail profile image url String thumbnailImageUrl = kakaoProfile.getThumbnailImageUrl(); // If the player has unlinked this app or not // If you want to display information on whether or not to leave the UI, use this flag boolean isUnregistered = kakaoProfile.isUnregistered(); } // List of recipients who have not yet joined the app // Player ID is not provided because the user has not signed up for the app List<KGKakaoProfile> invitees = receivers.getInvitees(); for (KGKakaoProfile kakaoProfile : invitees) { // Receiver's nickname String nickname = kakaoProfile.getNickname(); // Receiver's KakaoTalk thumbnail profile image url String thumbnailImageUrl = kakaoProfile.getThumbnailImageUrl(); } } else if (result.getCode() == KGResult.KGResultCode.NOT_KAKAOTALK_USER) { // The user is not a KakaoTalk user. } else { // Fail... } } }); |
iOS 예제
#import <KakaoGame/KakaoGame.h> // [TODO] Set event Id int eventId = 511; // Querying this invitation event // Querying the list of friends I sent an invitation to [KGKakaoInvitation loadReceiversWithEventId:eventId completionHandler:^(NSError *error, NSArray *joiners, NSArray *invitees) { if (IS_SUCCESS(error) == YES) { // Success // List of players joined to the app, including unlink users for (KGPlayer *joiner in joiners) { // Receiver's playerId NSString *playerId = joiner.playerId; KGKakaoProfile *kakaoProfile = (KGKakaoProfile*)joiner.idpProfile; // Receiver's nickname NSString *nickname = kakaoProfile.nickname; // Receiver's KakaoTalk thumbnail profile image url NSString *thumbnailImageUrl = kakaoProfile.thumbnailImageUrl; // If the player has unlinked this app or not // If you want to display information on whether or not to leave the UI, use this flag BOOL isUnregistered = kakaoProfile.isUnregistered; } // List of recipients who have not yet joined the app // Player ID is not provided because the user has not signed up for the app for (KGKakaoPrfoile *invitee in invitees) { // Receiver's nickname NSString *nickname = invitee.nickname; // Receiver's KakaoTalk thumbnail profile image url NSString *thumbnailImageUrl = invitee.thumbnailImageUrl; } } else if (error.code == KGErrorNotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail... } }]; |
21.1.6. Querying the count of players who invited you
This section shows an example of a query the count of players who invited you.
Unity 예제
using KakaoGame.SDK; using KakaoGame.SDK.Kakao; // [TODO] Set event Id int eventId = 511; // Querying this invitation event KGKakaoInvitation.LoadSendersCount(eventId, (result, count) => { if (result.isSuccess) { // Success // Get the number of players who invited you int senderCount = count; } else { // Fail... } }); |
Android 예제
import com.kakaogame.KGKakaoInvitation; import com.kakaogame.KGKakaoInvitation.KGInvitationReceviersResponse; import com.kakaogame.KGPlayer; import com.kakaogame.KGKakaoProfile; import com.kakaogame.KGResult; // [TODO] Set event Id int eventId = 511; // Querying this invitation event KGKakaoInvitation.loadSendersCount(eventId, new KGResultCallback<Integer>() { @Override public void onResult(KGResult<Integer> result) { if (result.isSuccess()) { // Success int count = result.getContent(); // Get the number of players who invited you } else { // Fail... } } }); |
iOS 예제
#import <KakaoGame/KakaoGame.h> // [TODO] Set event Id int eventId = 511; // Querying this invitation event [KGKakaoInvitation loadSendersCountWithEventId:eventId completionHandler:^(NSError *error, int count) { if (IS_SUCCESS(error) == YES) { // Success // Get the number of players who invited you int senderCount = count; } else { // Fail... } }]; |
21.1.7. Querying the list of players who invited you
This section shows an example of a query the list of players who invited you.
Unity 예제
using KakaoGame.SDK; using KakaoGame.SDK.Kakao; // [TODO] Set event Id int eventId = 511; // Querying this invitation event // Querying the list of players who invited you KGKakaoInvitation.LoadSenders(eventId, (result, invitationSenders) => { if (result.isSuccess) { // Success // Get the list of players who invited you if (invitationSenders != null && invitationSenders.Count > 0) { foreach (KGPlayer player in invitationSenders) { // Get the playerId string playerId = player.playerId; KGKakaoProfile kakaoProfile = (KGKakaoProfile)player.idpProfile; // player's nickname string nickname = kakaoProfile.nickname; // player's KakaoTalk thumbnail image url string thumbnailImageUrl = kakaoProfile.thumbnailImageUrl; } } else { // No players who invited you } } else if (result.code == KGResultCode.NotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail... } }); |
Android 예제
import com.kakaogame.KGKakaoInvitation; import com.kakaogame.KGPlayer; import com.kakaogame.KGKakaoProfile; import com.kakaogame.KGResult; // [TODO] Set event Id int eventId = 511; // Querying this invitation event // Querying the list of players who invited you KGKakaoInvitation.loadSenders(eventId, new KGResultCallback<List<KGPlayer>>() { @Override public void onResult(KGResult<List<KGPlayer>> result) { if (result.isSuccess()) { // Success // Get the list of players who invited you List<KGPlayer> invitationSenders = result.getContent(); if (invitationSenders != null && invitationSenders.size() > 0) { for (KGPlayer player : invitationSenders) { // Get the playerId String playerId = player.getPlayerId(); KGKakaoProfile kakaoProfile = (KGKakaoProfile) player.getIdpProfile(); // player's nickname String nickname = kakaoProfile.getNickname(); // player's KakaoTalk thumbnail image url String thumbnailImageUrl = kakaoProfile.getThumbnailImageUrl(); } } else { // No players who invited you } } else if (result.getCode() == KGResult.KGResultCode.NOT_KAKAOTALK_USER) { // The user is not a KakaoTalk user. } else { // Fail... } } }); |
iOS 예제
#import <KakaoGame/KakaoGame.h> // [TODO] Set event Id int eventId = 511; // Querying this invitation event // Querying the list of players who invited you [KGKakaoInvitation loadSendersWithEventId:eventId completionHandler:^(NSError *error, NSArray *invitationSenders) { if (IS_SUCCESS(error) == YES) { // Success // Get the list of players who invited you if (invitationSenders != nil && [invitationSenders count] > 0) { for (KGPlayer *invitationSender in invitationSenders) { // Get the playerId NSString *playerId = invitationSender.playerId; KGKakaoProfile *kakaoProfile = (KGKakaoProfile*)invitationSender.idpProfile; // player's nickname NSString *nickname = kakaoProfile.nickname; // player's KakaoTalk thumbnail image url NSString *thumbnailImageUrl = kakaoProfile.thumbnailImageUrl; } } } else if (error.code == KGErrorNotKakaoTalkUser) { // The user is not a KakaoTalk user. } else { // Fail... } }]; |