메타 데이터의 끝으로 건너뛰기
메타 데이터의 시작으로 이동

You are viewing an old version of this content. View the current version.

현재와 비교 View Version History

« 이전 버전 8 다음 »

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.

import com.kakaogame.KGTApplication;
import com.kakaogame.KGTConfig;

/**
 * When using a single app
 */
KGTConfig config = new KGTConfig();
config.setAppInfo(
	"909428", // appID
	"c3c38bbfa3828b342d946e9770c974d0", // appSecret
	"1.0.0", // appVersion
	"googlePlay", // market
	"14", // ageRating
	KGTServerType.QA, // server type
	KGTLogLevel.Error // log level
);

/**
 * When using an app group
 */
Map<String, String> appsForAppGroup = new HashMap<>();
appsForAppGroup.put("909428", "c3c38bbfa3828b342d946e9770c974d0");
appsForAppGroup.put("921478", "5891c32124ca35821890a0bc1cec77a5");

KGTConfig config = new KGTConfig();
config.setAppGroupInfos(
	"tubeAppGroup", // appGroupId
	appsForAppGroup, // app info map
	"1.0.0", // appVersion
	"googlePlay", // market
	"14", // ageRating
	KGTServerType.QA, // server type
	KGTLogLevel.Error // log level
);


KGTApplication.initSDK(this, config);

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.

import com.kakaogame.KGTApplication;
import com.kakaogame.KGTIdpProfile;
import com.kakaogame.KGTPlayer;
import com.kakaogame.KGTResult;

KGTApplication.start(activity, null, result -> {
	if (result.isSuccess()) {
		// If the start is successful

		// Check if auto-login is enabled
		boolean isLoggedIn = KGTPlayer.isLoggedIn();

		if (isLoggedIn) {
			// The current Player's ID issued by the platform
			String playerId = KGTPlayer.getCurrentPlayer().getPlayerId();

			// Platform access token (ZAT)
			String accessToken = KGTPlayer.getCurrentPlayer().getAccessToken();

			// Retrieve the current IDP authentication information
			KGTIdpProfile idpProfile = KGTPlayer.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.
		int resultCode = result.getCode();

		if (resultCode == KGTResult.KGTResultCode.NETWORK_FAILURE 
			|| resultCode == KGTResult.KGTResultCode.SERVER_TIMEOUT
			|| resultCode == KGTResult.KGTResultCode.SERVER_CONNECTION_FAILED) {
			// [TODO] If a network error occurs, inform the user that the start failed due to a network issue and retry.
		} else {
			// [TODO] If other errors occur, provide an error notification 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.

import com.kakaogame.KGTApplication;
import com.kakaogame.KGTResult;
 
KGTApplication.pause(activity, result -> {
	//
});

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.

import com.kakaogame.KGTApplication;
import com.kakaogame.KGTResult;
 
KGTApplication.resume(activity, result -> {
	if (result.isSuccess()) {
		// [TODO] If 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.getCode() == KGTResult.KGTResultCode.AUTH_FAILURE 
			|| result.getCode() == KGTResult.KGTResultCode.IDP_AUTH_FAILURE) {
			// [TODO] In case of authentication failure, move to the start screen and perform the new login flow again.
		} else {
			// [TODO] If other errors occur, provide an error notification and request a retry of the start process. - If the issue persists, check the error code and logs to determine the cause.
		}
	}
});

Adding a New Intent Receive Setting

This setting is required if you are using the Android SDK directly.

Add a callback inside MainActivity of the game as shown below.

If you do not add this setting, there will be a problem checking your game's funnel through 'game-play' page on KakaoTalk. Please be sure to add.

And when using Unity, set the corresponding MainActivity as the main activity in Unity Assets / Plugins / Android / AndroidManifest.xml file.

(If you are using the KakaoGames Unity or Unreal SDK, this setting is configured automatically, so no additional setup is required.)

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
     
    // Update the current activity with the new intent
    this.setIntent(intent);
}

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.

import com.kakaogame.KGTApplication;
import com.kakaogame.KGTIdpProfile;
import com.kakaogame.KGTPlayer;
import com.kakaogame.KGTResult;

// Set the IdpCode for the login
KGTIdpProfile.KGTIdpCode code = KGTIdpCode.Kakao;

// Log in with a specific IDP
KGTPlayer.login(activity, code, result -> {
	if (result.isSuccess()) {
		// IDP login and platform login succeeded

		// The current Player's ID issued by the platform
		String playerId = KGTPlayer.getCurrentPlayer().getPlayerId();

		// Platform access token
		String accessToken = KGTPlayer.getAccessToken();

		// Retrieve the current IDP authentication information
		KGTIdpProfile idpProfile = KGTPlayer.getCurrentPlayer().getIdpProfile();

		// [TODO] Since 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.

		if (result.getCode() == KGTResult.KGTResultCode.NETWORK_FAILURE 
			|| result.getCode() == KGTResult.KGTResultCode.SERVER_TIMEOUT
			|| result.getCode() == KGTResult.KGTResultCode.SERVER_CONNECTION_FAILED) {
			// [TODO] If a network error occurs, prompt the user to retry logging in.
		} else if (result.getCode() == KGTResult.KGTResultCode.USER_CANCELED) {
			// [TODO] Since the user canceled during the login process, the login screen should be maintained.
		} else if (result.getCode() == KGTResult.KGTResultCode.BLOCKED_BY_POLICY) {
			// [TODO] The login was attempted from a blocked country code or IP range. Handle accordingly.
		} 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.

import com.kakaogame.KGTPlayer;
import com.kakaogame.KGTResult;

// Logout request
KGTPlayer.logout(activity, false, result -> {
	if (result.isSuccess()) {
		// Logout successful

		// [TODO] Return to the start screen
	} else {
		// Logout failed
	}
});

Unregistration

  • 탈퇴 UI를 개발사에서 직접 구현하고 싶을 경우(탈퇴 UI를 사용하고 싶지 않은 경우)를 위해서, 탈퇴 API가 제공됩니다.

Unregistering Without Using the Default Unregistration UI

기본 탈퇴 UI를 사용하지 않는 탈퇴하는 예제입니다.

import com.kakaogame.KGTPlayer;
import com.kakaogame.KGTResult;

// Unregister request
KGTPlayer.unregister(activity, false, 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.

import com.kakaogame.KGTPlayer;
import com.kakaogame.KGTIdpProfile;
import com.kakaogame.KGTResult;

// Set the IdpCode to log in with
KGTIdpProfile.KGTIdpCode code = KGTIdpCode.Kakao;

// Connect account with a specific idp
KGTPlayer.connect(activity, code, result -> {
	if (result.isSuccess()) {
		// IDP connection successful
		// Player ID will not change.
	} else {
		// IDP connection failed

		if (result.getCode() == KGTResult.KGTResultCode.INVALID_PARAMETER) {
			// Invalid parameter passed
			// e.g., activity is null
		} else if (result.getCode() == KGTResult.KGTResultCode.NOT_AUTHORIZED) {
			// The current state is not authorized
		} else if (result.getCode() == KGTResult.KGTResultCode.INVALID_STATE) {
			// The currently authenticated IDP is not device authentication
		} else if (result.getCode() == KGTResult.KGTResultCode.ALREADY_USED_IDP_ACCOUNT) {
			// The account is already authenticated
		} else {
			// Other errors occurred
		}
	}
});

Profile

Retrieve My Information

This is an example of retrieving my information.

import com.kakaogame.KGTPlayer;

KGTPlayer localPlayer = KGTPlayer.getCurrentPlayer();

Retrieve My IDP Information

This is an example of retrieving my IDP profile information.
You can retrieve the information provided by each IDP profile. 

import com.kakaogame.KGTPlayer;
import com.kakaogame.KGTIdpProfile;

KGTIdpProfile idpProfile = KGTPlayer.getCurrentPlayer().getIdpProfile();

System Information

Retrieve Language Code

Retrieves the language setting information of the device, returning a language code according to the ISO 639-1 standard.

import com.kakaogame.KGTSystem;

String languageCode = KGTSystem.getLanguageCode();

Retrieve Language Tag

import com.kakaogame.KGTSystem;

String languageCode = KGTSystem.getLanguageTag();

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.

import com.kakaogame.KGTSystem;

String countryCode = KGTSystem.getCountryCode();

Retrieve IP-based Country Code

Returns the country code based on the IP of the network to which the device is currently connected.

import com.kakaogame.KGTSystem;

String countryCode = KGTSystem.getGeoCountryCode();

Retrieve Device ID

Returns a value that uniquely identifies the device. This value changes if the device is reset.

import com.kakaogame.KGTSystem;

String deviceId = KGTSystem.getDeviceId();

Retrieve Device Model

Returns the model information of the current device.

import com.kakaogame.KGTSystem;

String deviceModel = KGTSystem.getDeviceModel();

Retrieve OS Name

Returns the name of the current device's OS (android/ios).

import com.kakaogame.KGTSystem;

String osName = KGTSystem.getOSName();

Retrieve Network Connection Status

Returns whether the current device is connected to an external network.

import com.kakaogame.KGTSystem;

boolean networkConnected = KGTSystem.isNetworkConnected();

Retrieve Connected Network Type

Retrieves the type of network to which the current device is connected (wifi/cellular/unknown).

import com.kakaogame.KGTSystem;

String networkType = KGTSystem.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.

import com.kakaogame.KGTKakaoTalk;

// Display the view to set KakaoTalk game message reception preferences
KGTKakaoTalk.showSetting(activity, result -> {
	if (result.isSuccess()) {
		// Successfully set the KakaoTalk game message reception settings
		boolean allowMessage = result.getContent(); //  Whether message reception is allowed as per the settings
	} else if (result.getCode() == KGTResult.KGTResultCode.NOT_KAKAOTALK_USER) {
		// The logged-in user is not a 'KakaoTalk' user. This occurs when the user is only registered with KakaoStory and not KakaoTalk.
	} else {
		// Failed to set the KakaoTalk game message reception settings
	}
});

Retrieve KakaoTalk Profile

This is an example of how to retrieve your own KakaoTalk profile.

import com.kakaogame.KGTKakaoTalk;
import com.kakaogame.KGTKakaoTalkProfile;

// Retrieve KakaoTalk profile
KGTKakaoTalk.talkProfile(result -> {
	if (result.isSuccess()) {
		// Successfully retrieved KakaoTalk profile
		talkProfile = result.getContent(); // The KakaoTalk profile information of the logged-in user
	} else if (result.getCode() == KGTResult.KGTResultCode.NOT_KAKAOTALK_USER) {
		// The logged-in user is not a 'KakaoTalk' user. This occurs when the user is only registered with KakaoStory and not KakaoTalk.
	} else {
		// Failed to retrieve KakaoTalk profile
	}
});

Retrieve KakaoTalk Game Friend List

This is an example of how to retrieve your KakaoTalk game friend list.

import com.kakaogame.KGTKakaoTalk;
import com.kakaogame.KGTKakaoFriendProfile;

// Retrieve the list of game friends
KGTKakaoTalk.friends(result -> {
	if (result.isSuccess()) {
		// Successfully retrieved KakaoTalk game friends list.
		List<KGTPlayer> friendList = result.getContent(); // Game friends list
		
		for (KGTPlayer player : friendList) {
            KGTKakaoFriendProfile kakaoProfile = (KGTKakaoFriendProfile)player.getIdpProfile();
        }
	} else if (result.getCode() == KGTResult.KGTResultCode.NOT_KAKAOTALK_USER) {
		// The logged-in user is not a 'KakaoTalk' user. This occurs when the user is only registered with KakaoStory and not KakaoTalk.
	} 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.

import com.kakaogame.KGTKakaoFriendProfile;
import com.kakaogame.KGTKakaoTalk;
import com.kakaogame.KGTKakaoTalkProfile;

// Friend object retrieved through the friends API
KGTKakaoFriendProfile kakaoProfile; // Kakao profile (KGTKakaoFriendProfile object)

// [TODO] Set the Template Id
String templateId = "";

// [TODO] Set the arguments for the message template
Map<String, String> args = new LinkedHashMap<>();
if (talkProfile != null) {
	args.put("${nickname}", talkProfile.getNickname());
}
args.put("rog_link", "test=100&hello=20111");
args.put("bruce2", "test=100&hello=20111");

// Send a KakaoTalk game message
KGTKakaoTalk.sendGameMessage(kakaoProfile, templateId, args, result -> {
	if (result.isSuccess()) {
		// Successfully sent a KakaoTalk chat message
	} else {
		if (result.getCode() == KGTResult.KGTResultCode.MESSAGE_SETTING_DISABLE) {
			// The recipient has set message reception to disabled
		} else if (result.getCode() == KGTResult.KGTResultCode.EXCEED_DAILY_USAGE) {
			// Occurs when the daily quota for sending messages to a specific app (regardless of the recipient) is exceeded.
		} else if (result.getCode() == KGTResult.KGTResultCode.EXCEED_MONTHLY_USAGE) {
			// 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.

import com.kakaogame.KGTKakaoTalk;
import com.kakaogame.KGTKakaoTalkProfile;
import com.kakaogame.KGTKakaoUser;

// [TODO] Set whether to display as a popup window
boolean isSingle = true;

// [TODO] Set whether to display as a popup window
boolean isPopup = true;
  
// [TODO] Set the template Id
String templateId = "";

// [TODO] Set the parameters for the message template
Map<String, String> args = new LinkedHashMap<>();
if (talkProfile != null) {
	args.put("${nickname}", talkProfile.getNickname());
}

KGTKakaoTalk.sendInviteMessage(activity, isSingle, isPopUp, templateId, args, result -> {
	if (result.isSuccess()) {
		// Successfully sent KakaoTalk invite message
		for (KGTKakaoUser kakaoUser : result.getContent()) {
			// Check the list of users who received the invite message
		}
	} else {
		// Failed to send to all users (need to return a common cause)
		if (result.getCode() == KGTResult.KGTResultCode.MESSAGE_SETTING_DISABLE) {
			// The recipient has set message reception to disabled
		} else if (result.getCode() == KGTResult.KGTResultCode.EXCEED_DAILY_USAGE) {
			// Occurs when the daily quota for sending messages to a specific app (regardless of the recipient) is exceeded.
		} else if (result.getCode() == KGTResult.KGTResultCode.EXCEED_MONTHLY_USAGE) {
			// Occurs when the monthly quota for sending messages to a specific person for a specific app is exceeded.
		} else {
			// Failed to send KakaoTalk invite message
		}
	}
});

Adding a KakaoTalk Channel

This is an example of how to add a KakaoTalk channel.

import com.kakaogame.KGTKakaoTalk;

// [TODO] Set the channel Id
int channelId = 0;

KGTKakaoTalk.addChannel(plusFriendId, result -> {
	if (result.isSuccess()) {
		// Successfully added the channel
	} else if (result.getCode() == KGTResult.KGTResultCode.NOT_KAKAOTALK_USER) {
		// The logged-in user is not a 'KakaoTalk' user. This occurs when the user is only registered with KakaoStory and not KakaoTalk.
	} else {
		// Failed to add the channel
	}
});

Google Games

Show Achievement Screen

매크로 처리 오류 'excerpt-include' : User 'null' does not have permission to view the page 'EN_구글 게임 SDK 예제'.

import com.kakaogame.KGTGoogleGamesAchievements;

// Show Google Games achievement information screen
KGTGoogleGamesAchievements.showAchievement(activity);

Achievement Unlocked

매크로 처리 오류 'excerpt-include' : User 'null' does not have permission to view the page 'EN_구글 게임 SDK 예제'.

import com.kakaogame.KGTGoogleGamesAchievements;

// [TODO] Set achievement ID
String id = "";

// Unlock achievement
KGTGoogleGamesAchievements.unlock(id);

Display Achievement

매크로 처리 오류 'excerpt-include' : User 'null' does not have permission to view the page 'EN_구글 게임 SDK 예제'.

import com.kakaogame.KGTGoogleGamesAchievements;

// [TODO] Set achievement ID
String id = "";

KGTGoogleGamesAchievements.reveal(id);

Increase Achievement Level

매크로 처리 오류 'excerpt-include' : User 'null' does not have permission to view the page 'EN_구글 게임 SDK 예제'.

import com.kakaogame.KGTGoogleGamesAchievements;

// [TODO] Set achievement ID
String id = "";
int numSteps = 0;

KGTGoogleGamesAchievements.setSteps(id, numSteps);

Set Achievement Level

매크로 처리 오류 'excerpt-include' : User 'null' does not have permission to view the page 'EN_구글 게임 SDK 예제'.

import com.kakaogame.KGTGoogleGamesAchievements;

// [TODO] Set achievement ID
String id = "";
int numSteps = 0;

KGTGoogleGamesAchievements.increment(id, numSteps);
  • 레이블 없음