Initialization and Status Change Event Processing
SDK Initialization
This process sets and initializes the app information used by the SDK.
It must be called before any other API when the game starts.
#include "KakaoGameV4.h" /** * Perform initialization using the information set in Unreal Editor */ FKGTApplication::InitSDK();
Start
When a game is started, it must call the Start function to notify the Kakao Game SDK that it has been started. UI functions such as platform announcements, update news, and term agreements are performed when the Start function of the Kakao Game SDK is called. If there exists a prior user login record, the automatic login function is also performed, and the result is sent through the callback function inputted in the game when the method is called. Therefore, the game can use the results to decide whether to authenticate the user first or whether to resume a previous game.
#include "KakaoGameV4.h" FKGTApplication::Start(FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // If the start is successful // Check if auto-login is enabled bool isLoggedIn = FKGTPlayer::IsLoggedIn(); if (isLoggedIn) { // The current Player's ID issued by the platform FString playerId = FKGTPlayer::GetCurrentPlayer().GetPlayerId(); // Platform access token FString accessToken = FKGTPlayer::GetAccessToken(); // Retrieve the current IDP authentication information FKGTIdpProfile idpProfile = FKGTPlayer::GetCurrentPlayer().GetIdpProfile(); // [TODO] Move to the game screen. } else { // [TODO] If auto-login is not enabled, move to the login screen. } } else { // If the start fails - since initialization failed, retry the start or close the app. int32 resultCode = result.GetCode(); if (resultCode == FKGTResultCode::NetworkFailure || resultCode == FKGTResultCode::ServerTimeout || resultCode == FKGTResultCode::ServerConnectionFailed) { // [TODO] If a network error occurs, notify the user that the start failed due to a network issue and retry. } else { // [TODO] If other errors occur, notify the user and request a retry of the start process. If the issue persists, check the error code and logs to determine the cause. } } }));
Pause
If the game is moved to the background, the game must call the Pause API to notify the Kakao Game SDK that it has become inactive.
When the Pause API is called, the Kakao Game SDK disconnects the connected session and stops periodically sending heartbeats to prevent battery consumption.
#include "KakaoGameV4.h" // Called when the game enters a background state (e.g., switching to another app or exiting via the home button). // Register with ApplicationWillEnterBackgroundDelegate so that SDK Pause can be called. FCoreDelegates::ApplicationWillEnterBackgroundDelegate.AddUObject(this, &UApplicationWidget::Pause); FKGTApplication::Pause(FKGTResultDelegate::CreateLambda([=](FKGTResult result) { // The result always returns a success (200) response. }));
Resume
If the game is moved back to the foreground from the background, it must call the Resume API to notify the Kakao Game SDK that it has become active. The Kakao Game SDK checks whether the authentication has expired when the Resume method is called and restores the session depending on the check. The result is then sent through the callback function inputted in the game when the method is called. The game can use the results to decide whether to authenticate the user again or whether to resume a previous game.
#include "KakaoGameV4.h" // Called when the game returns to the foreground // Register with ApplicationHasEnteredForegroundDelegate so that SDK Resume can be called. FCoreDelegates::ApplicationHasEnteredForegroundDelegate.AddUObject(this, &UApplicationWidget::Resume); FKGTApplication::Resume(FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // [TODO] If the resume is successful, resume the game screen. } else { // [TODO] If resume fails, navigate to the login screen if it’s an authentication failure; otherwise, show an error popup and check if the user wants to retry. if (result.Code == FKGTResultCode::AuthFailure || result.Code == FKGTResultCode::IdpAuthFailure) { // [TODO] If the start fails - Initialization failed, so you should either retry the start or close the app. } else { // [TODO] If other errors occur, provide an error notification and retry the resume. If the issue persists, close the app. } } });
Setting Up Auto Login in a Windows Environment
This feature is supported in the Windows environment. If you do not use the default login UI provided by the SDK and instead implement your own login UI, the SDK offers a feature to set up auto login. If you do not configure auto login, the SDK will not create a file for automatic login by default. The file for auto login is created and stored in an encrypted format in the folder ".kakaogames" under the name ".access". This is because multiple users can exist on a single PC." When a game is uninstalled and then reinstalled, if the auto login file remains, the SDK checks whether an encrypted ".access" file exists in the location of the Windows SDK file (KakaoGame.dll). If the file is valid, the SDK loads the file containing the auto login information and performs the auto login. If the auto login files are corrupted, the SDK will delete them. If the auto login file exists and the user logs out or withdraws, the auto login file will be deleted.
#include "KakaoGameV4.h" // Set whether to use auto-login; if not set, it defaults to not using auto-login // When auto-login is enabled and login is successful, auto-login information is generated // If auto-login information exists, auto-login will proceed automatically during the next KGTApplication start, so to remove the auto-login information, you need to log out bool useAutoLogin = true; FKGTApplication::SetUseAutoLogin(useAutoLogin);
Login
The login UI can be customized and applied by the developer.
Considerations When Implementing Login UI Directly
Login APIs are provided for each IDP (Identity Provider).
When implementing the login screen, the developer should place login buttons for each IDP and implement the logic so that clicking each button calls the corresponding IDP's login API.
If a global build is provided, the visibility of IDP buttons should be handled according to the country. For example, in South Korea, Kakao Login should be provided, while in other countries, Facebook Login may be provided.
To differentiate by country, an API in the KGTSystem class is provided to retrieve the countryCode.
After a successful login, if the settings screen is displayed, it should be implemented so that the PlayerID is shown as the member number.
Logging In Without Using the Default Login UI
This is an example of logging in without using the default login UI. If the login IDP varies by country, use the API to retrieve the country and handle branching accordingly. Guest Verification In the case of guest login, an alert popup must be implemented by the developer. This is a mandatory checkpoint during Kakao Games inspection. Before proceeding with guest verification, an alert popup should be displayed with the message: "If you delete the game or change devices, game data may be lost when logging in as a guest." This allows the user to choose whether to continue with guest verification or cancel. Example) When guest login is used, if the app is deleted or the device information is changed, the game cannot continue with the previous playerId. If using the default login, the SDK provides this alert automatically.
#include "KakaoGameV4.h" // Set the IdpCode for the login EKGTIdpCode idpCode = EKGTIdpCode::Kakao; // Log in with a specific IDP FKGTPlayer::Login(idpCode, FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // The current Player's ID issued by the platform FString playerId = FKGTPlayer::GetCurrentPlayer().GetPlayerId(); // Platform access token FString accessToken = FKGTPlayer::GetAccessToken(); // Retrieve the current IDP authentication information FKGTIdpProfile idpProfile = FKGTPlayer::GetCurrentPlayer().GetIdpProfile(); // [TODO] Since the login was successful, proceed to the game screen. } else { // IDP login or platform login failed // [TODO] If login fails, inform the user and prompt them to retry. int32 resultCode = result.GetCode(); if (resultCode == FKGTResultCode::NetworkFailure || resultCode == FKGTResultCode::ServerTimeout || resultCode == FKGTResultCode::ServerConnectionFailed) { // [TODO] If a network error occurs, notify the user that the start failed due to a network issue and retry. } else if (resultCode == FKGTResultCode::Forbidden) { // [TODO] During the CBT period, authentication may not be possible for users who are not allowed. Provide an appropriate notification to the user. } else if (resultCode == FKGTResultCode::UserCanceled) { // [TODO] Since the user canceled during the login process, the login screen should be maintained. } else { // [TODO] If other errors occur, provide an error notification and prompt the user to retry logging in. It is necessary to check the error code and logs to determine the cause. } } }));
Logging In Through the Launcher
This API is used when performing SDK login through a launcher (supported in Windows environments). Login is performed using the bridgeToken received from the launcher. After logging in, any additional information received through the launcher can be checked in the player information.
#include "KakaoGameV4.h" // The bridgeToken received through the launcher FString bridgeToken = ""; FKGTPlayer::LoginWithBridgeToken(bridgeToken, FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // The current Player's ID issued by the platform FString playerId = FKGTPlayer::GetCurrentPlayer().GetPlayerId(); // Platform access token FString accessToken = FKGTPlayer::GetAccessToken(); // Retrieve the current IDP authentication information FKGTIdpProfile idpProfile = FKGTPlayer::GetCurrentPlayer().GetIdpProfile(); // Additional information received through the launcher TSharedPtr<FJsonObject> bridgeTokenPayload = FKGTPlayer::GetCurrentPlayer().GetBridgeTokenPayload(); // [TODO] Log in to the game server and proceed to the game screen } else { // Handle login failure. // [TODO] If login fails, inform the user and prompt them to retry. int32 resultCode = result.GetCode(); if (resultCode == FKGTResultCode::NetworkFailure || resultCode == FKGTResultCode::ServerTimeout || resultCode == FKGTResultCode::ServerConnectionFailed) { // [TODO] If a network error occurs, prompt the user to retry logging in. } else if (resultCode == FKGTResultCode::Forbidden) { // [TODO] During the CBT period, authentication may not be possible for users who are not allowed. Display a notification to the user, and after clicking confirm, implement the app to exit. } else if (resultCode == FKGTResultCode::UserCanceled) { // [TODO] Since the user canceled during the login process, the login screen should be maintained. } else { // [TODO] If other errors occur, provide an error notification and prompt the user to retry logging in. // It is necessary to check the error code and logs to determine the cause. } } }));
Logout
The logout UI must be implemented directly by the developer.
Logout APIs are provided for each logout UI.
Logging Out Without Using the Default Logout UI
This is an example of logging out without using the default logout UI.
#include "KakaoGameV4.h" // Logout request FKGTPlayer::Logout(FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // Logout successful // [TODO] Return to the start screen } else { // Logout failed } }));
Unregistration
If the developer wishes to implement the unregistration UI directly (or does not want to use the provided unregistration UI), an unregistration API is available.
Unregistering Without Using the Default Unregistration UI
This is an example of unregistering without using the default unregistration UI.
#include "KakaoGameV4.h" // Unregistration (account deletion) request FKGTPlayer::Unregister(showUI, FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // Unregistration successful // [TODO] Return to the start screen } else { // Unregistration failed } }));
Account Linking
If the developer wishes to implement the account linking UI directly (or does not want to use the default account linking UI), an account linking API is provided for each IDP.
The developer should place account linking buttons for each IDP on the account linking screen, and implement the logic so that clicking each button calls the corresponding IDP's account linking API.
Linking Accounts Without Using the Default Account Linking UI
This is an example of linking accounts without using the default account linking UI.
If account linking is successful, the player ID will remain the same.
#include "KakaoGameV4.h" // Set the IdpCode for the login EKGTIdpCode idpCode = EKGTIdpCode::Kakao; // Connect the account with a specific IDP FKGTPlayer::Connect(idpCode, FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // IDP connection successful // The Player ID does not change. } else { // IDP connection failed int32 resultCode = result.GetCode(); if (resultCode == FKGTResultCode::NotAuthorized) { // If the current session is not logged in } else if (resultCode == FKGTResultCode::InvalidState) { // If the currently authenticated IDP is not eligible for account connection } else if (resultCode == FKGTResultCode::AlreadyUsedIDPAccount) { // If the account is already connected to another IDP } else { // Other errors occurred } } }));
Profile
Retrieve My Information
This is an example of retrieving my information.
#include "KakaoGameV4.h" FKGTPlayer player = FKGTPlayer::GetCurrentPlayer(); // Platform playerId FString playerId = player.GetPlayerId(); // Platform AccessToken FString accessToken = FKGTPlayer::GetAccessToken(); // idpProfile information FKGTIdpProfile idpProfile = player.GetIdpProfile();
Retrieve My IDP Information
This is an example of retrieving my IDP profile information.
You can retrieve the information provided by each IDP profile.
#include "KakaoGameV4.h" FKGTPlayer player = FKGTPlayer::GetCurrentPlayer(); // Retrieve IDP information FKGTIdpProfile idpProfile = player.GetIdpProfile(); EKGTIdpCode idpCode = idpProfile.GetIdpCode(); FString idpUserId = idpProfile.GetIdpUserId(); // Retrieve Kakao IDP information // If the login state is with Kakao if (idpCode == EKGTIdpCode::Kakao) { // Retrieve Kakao IDP information FKGTKakaoProfile *kakaoProfile = (FKGTKakaoProfile*)&idpProfile; // Kakao UUID FString uuid = kakaoProfile->GetUUID(); // If the same Kakao user is using a different app, return the same group user token FString groupUserToken = kakaoProfile->GetGroupUserToken(); // Remaining number of invites that can be sent today int32 remainingInviteCount = kakaoProfile->GetRemainingInviteCount(); // Whether the app is registered bool isAppRegistered = kakaoProfile->IsAppRegistered(); // Whether message reception is allowed bool isAllowedMessage = kakaoProfile->IsAllowedMessage(); }
System Information
Retrieve Language Code
Retrieves the language setting information of the device, returning a language code according to the ISO 639-1 standard.
#include "KakaoGameV4.h" FString languageCode = FKGTSystem::GetLanguageCode();
Retrieve Country Code
The SDK collects the country code based on the initial GeoIP. The country code follows the ISO 3166-1 alpha-2 standard, and if no country information is available, "zz" is returned.
The country code initially determined when the app is first run is maintained, but if the logged-in user's country code information differs, the user's country code information is followed.
#include "KakaoGameV4.h" FString countryCode = FKGTSystem::GetCountryCode();
Retrieve IP-based Country Code
Returns the country code based on the IP of the network to which the device is currently connected.
#include "KakaoGameV4.h" FString geoCountryCode = FKGTSystem::GetGeoCountryCode();
Retrieve Device ID
Returns a value that uniquely identifies the device. This value changes if the device is reset.
#include "KakaoGameV4.h" FString deviceId = FKGTSystem::GetDeviceId();
Retrieve Device Model
Returns the model information of the current device.
#include "KakaoGameV4.h" FString deviceModel = FKGTSystem::GetDeviceModel();
Retrieve OS Name
Returns the name of the current device's OS (android/ios).
#include "KakaoGameV4.h" FString osName = FKGTSystem::GetOSName();
Retrieve Network Connection Status
Returns whether the current device is connected to an external network.
#include "KakaoGameV4.h" bool isNetworkConnected = FKGTSystem::IsNetworkConnected();
Retrieve Connected Network Type
Retrieves the type of network to which the current device is connected (wifi/cellular/unknown).
#include "KakaoGameV4.h" FString networkType = FKGTSystem::GetNetworkType();
Kakao Integration Feature
Setting Up KakaoTalk Game Message Reception
This is an example of how to set up the reception of KakaoTalk game messages for yourself.
#include "KakaoGameV4.h" // Display the view to set KakaoTalk game message reception preferences FKGTKakaoTalk::ShowSetting(FKGTResultWithIsAllowMeDelegate::CreateLambda([=](FKGTResult result, bool isAllowMe) { if (result.IsSuccess()) { // Successfully set KakaoTalk game message reception settings // isAllowMe - Whether message reception is allowed as per the settings } else if (result.GetCode() == FKGTResultCode::NotKakaoTalkUser) { // The logged-in user is not a 'KakaoTalk' user. (For cases where the user is not a KakaoTalk user) } else { // Failed to set KakaoTalk game message reception settings } }));
Retrieve KakaoTalk Profile
This is an example of how to retrieve your own KakaoTalk profile.
#include "KakaoGameV4.h" // Retrieve KakaoTalk profile FKGTKakaoTalk::TalkProfile(FKGTResultWithKakaoTalkProfileDelegate::CreateLambda([=](FKGTResult result, FKGTKakaoTalkProfile profile) { if (result.IsSuccess()) { // Successfully retrieved KakaoTalk profile // profile - The KakaoTalk profile information of the logged-in user } else if (result.GetCode() == FKGTResultCode::NotKakaoTalkUser) { // The logged-in user is not a 'KakaoTalk' user. (For cases where the user is not a KakaoTalk user) } else { // Failed to retrieve KakaoTalk profile } }));
Retrieve KakaoTalk Game Friend List
This is an example of how to retrieve your KakaoTalk game friend list.
#include "KakaoGameV4.h" // Retrieve game friend list FKGTKakaoTalk::Friends(FKGTResultWithPlayerListDelegate::CreateLambda([=](FKGTResult result, TArray<FKGTPlayer> playerList) { if (result.IsSuccess()) { // Successfully retrieved KakaoTalk game friends list. for (FKGTPlayer player : playerList) { FKGTIdpProfile idpProfile = player.GetIdpProfile(); FKGTKakaoFriendProfile *kakaoFriendProfile = (FKGTKakaoFriendProfile*)&idpProfile; } } else if (result.GetCode() == FKGTResultCode::NotKakaoTalkUser) { // The logged-in user is not a 'KakaoTalk' user. (For cases where the user is not a KakaoTalk user) } else { // Failed to retrieve KakaoTalk game friends list } }));
Sending KakaoTalk Game Messages
This is an example of sending a KakaoTalk game message using a message template.
If you want to receive specific parameters when the recipient taps the message to enter the game, you can set the exec parmin the message template.
When the recipient receives the message on KakaoTalk and taps the connection link, the app will launch and pass the exec param.
You can use this value to start a specific stage or provide predefined items. Please note that the exec param can only be used with game messages.
#include "KakaoGameV4.h" // Kakao friend profile retrieved through the friends API FKGTKakaoFriendProfile *kakaoFriendProfile; // [TODO] Set the template ID FString templateId = TEXT(""); // [TODO] Set the parameters for the message template TMap<FString, FString> argumentDic; argumentDic.Add(TEXT("${nickname}"), kakaoFriendProfile->GetNickname()); argumentDic.Add(TEXT("rog_link"), TEXT("test=100&hello=20111")); // Send a KakaoTalk game message FKGTKakaoTalk::SendGameMessage((*kakaoFriendProfile), templateId, argumentDic, FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // Successfully sent the KakaoTalk chat message } else { if (result.GetCode() == FKGTResultCode::MessageSettingDisabled) { // The recipient has set message reception to be disabled } else if (result.GetCode() == FKGTResultCode::ExceedDailyUsage) { // Occurs when the daily quota for sending messages to a specific app (regardless of the recipient) is exceeded. } else if (result.GetCode() == FKGTResultCode::ExceedMonthlyUsage) { // Occurs when the monthly quota for sending messages to a specific person for a specific app is exceeded. } else { // Failed to send KakaoTalk chat message } } }));
Sending KakaoTalk Friend Invitation Messages
This example demonstrates how to send an invitation message using the KakaoTalk Friend Picker.
Depending on the isSingle option, you can send invitation messages to multiple friends.
If you send invitation messages to multiple friends, a success response is returned even if only one friend successfully receives the message.
The isPopup option allows you to display the Friend Picker in a popup form. This feature is supported through the KakaoSDK but is not supported in the Windows SDK.
#include "KakaoGameV4.h" // [TODO] Set whether to display as a popup window bool isSingle = true; // [TODO] Set whether to display as a popup window bool isPopup = true; // [TODO] Set the template ID FString templateId = TEXT(""); // [TODO] Set the parameters for the message template TMap<FString, FString> argumentDic; argumentDic.Add(TEXT("${nickname}"), TEXT("nickname")); FKGTKakaoTalk::SendInviteMessage(isSingle, isPopup, templateId, argumentDic, FKGTResultWithKakaoUserListDelegate::CreateLambda([=](FKGTResult result, TArray<FKGTKakaoUser> users) { if (result.IsSuccess()) { // Successfully sent KakaoTalk invite message for (FKGTKakaoUser user : users) { // Check the list of users to whom the invite message was sent } } else { // If all failed (need to return a common cause) if (result.GetCode() == FKGTResultCode::MessageSettingDisabled) { // The recipient has set message reception to be disabled } else if (result.GetCode() == FKGTResultCode::ExceedDailyUsage) { // Occurs when the daily quota for sending messages to a specific app (regardless of the recipient) is exceeded. } else if (result.GetCode() == FKGTResultCode::ExceedMonthlyUsage) { // Occurs when the monthly quota for sending messages to a specific person for a specific app is exceeded. } else { // Failed to send KakaoTalk chat message } } }));
Adding a KakaoTalk Channel
This is an example of how to add a KakaoTalk channel.
#include "KakaoGameV4.h" // [TODO] Set the channel ID int32 channelId = 0; FKGTKakaoTalk::AddChannel(channelId, FKGTResultDelegate::CreateLambda([=](FKGTResult result) { if (result.IsSuccess()) { // Successfully added the channel } else if (result.GetCode() == FKGTResultCode::NotKakaoTalkUser) { // The logged-in user is not a 'KakaoTalk' user. (For cases where the user is not a KakaoTalk user) } else { // Failed to add the channel } }));
Retrieve the list of friends to whom I sent an invite message
This is an example of viewing the list of friends to whom I have sent invitation messages.
If a user is not registered, their information is delivered as an empty object.
#include "KakaoGameV4.h" // [TODO] Set the event ID int32 eventId = 0; // Retrieve the list of players I invited FKGTKakaoInvitation::Joiners(eventId, FKGTResultWithJoinersDelegate::CreateLambda([=](FKGTResult result, TArray<FKGTPlayer> players) { if (result.IsSuccess()) { // Successfully retrieved the list of players I invited for (FKGTPlayer player : players) { // Recipient's player ID FString playerId = player.GetPlayerId(); FKGTIdpProfile idpProfile = player.GetIdpProfile(); FKGTKakaoFriendProfile *kakaoProfile = (FKGTKakaoFriendProfile*)&idpProfile; // Recipient's nickname FString nickname = kakaoProfile->GetNickname(); // Recipient's profile thumbnail image FString thumbnailImageUrl = kakaoProfile->GetThumbnailImageUrl(); // Check if the recipient has a withdrawal history. Use this flag to display withdrawal information in the UI. bool isUnregistered = kakaoProfile->IsUnregistered(); } } else if (result.GetCode() == FKGTResultCode::NotKakaoTalkUser) { // The logged-in user is not a 'KakaoTalk' user. (For cases where the user is not a KakaoTalk user) } else { // Failed to retrieve the list } }));
Retrieve the count of friends to whom I sent an invite message
This is an example of checking the number of friends to whom I have sent invitation messages.
#include "KakaoGameV4.h" // [TODO] Set the event ID int32 eventId = 0; // Retrieve the count of players I invited FKGTKakaoInvitation::ReceiversCount(eventId, FKGTResultWithReceiversCountDelegate::CreateLambda([=](FKGTResult result, int32 totalReceiversCount, int32 joinersCount) { if (result.IsSuccess()) { // Successfully retrieved the counts // totalReceiversCount - Total number of friends // joinersCount - Number of friends who joined the game } else if (result.GetCode() == FKGTResultCode::NotKakaoTalkUser) { // The logged-in user is not a 'KakaoTalk' user. (For cases where the user is not a KakaoTalk user) } else { // Failed to retrieve the counts } }));
댓글 추가