|
| 1 | +Java Getting Started Guide |
| 2 | +---- |
| 3 | + |
| 4 | +This guide will help you make your first API call in Java. |
| 5 | + |
| 6 | +Java Project Setup |
| 7 | +---- |
| 8 | + |
| 9 | +* OS: This guide is written for Windows 10, however it should also work fine with a Mac |
| 10 | +* Installation |
| 11 | + * Download and install the latest JDK |
| 12 | + * http://www.oracle.com/technetwork/java/javase/downloads/index.html |
| 13 | + * Download the PlayFab ActionScriptSDK |
| 14 | + * https://api.playfab.com/sdks/download/java |
| 15 | + * Download the zip file, and extract it to a location of your choice {PlayFabJavaLocation} |
| 16 | +* New Project Setup |
| 17 | + * Create a new empty folder for your JavaGettingStarted project |
| 18 | + * Create a new empty text file called GettingStarted.java |
| 19 | + * We will modify this file in the next section |
| 20 | + * Import the PlayFab JavaSDK into this project |
| 21 | + * In Windows-Explorer, navigate to {PlayFabJavaLocation}/PlayFabClientSDK/src |
| 22 | + * Select everything in this folder (1 subfolder, and 2 jar files) |
| 23 | + * Copy it to your project folder |
| 24 | +* Your project folder should look like this: |
| 25 | + *  |
| 26 | +* PlayFab Installation Complete! |
| 27 | + |
| 28 | +Set up your first API call |
| 29 | +---- |
| 30 | + |
| 31 | +This guide will provide the minimum steps to make your first PlayFab API call. Confirmation will be visible as console-output text. |
| 32 | + |
| 33 | +In your favorite text-editor, update the contents of GettingStarted.java as follows: |
| 34 | +```Java |
| 35 | +import java.util.concurrent.*; |
| 36 | +import java.util.*; |
| 37 | + |
| 38 | +import com.playfab.PlayFabErrors.*; |
| 39 | +import com.playfab.PlayFabSettings; |
| 40 | +import com.playfab.PlayFabClientModels; |
| 41 | +import com.playfab.PlayFabClientAPI; |
| 42 | + |
| 43 | +public class GettingStarted |
| 44 | +{ |
| 45 | + private static boolean _running = true; |
| 46 | + |
| 47 | + public static void main(String[] args) { |
| 48 | + PlayFabSettings.TitleId = "144"; |
| 49 | + |
| 50 | + PlayFabClientModels.LoginWithCustomIDRequest request = new PlayFabClientModels.LoginWithCustomIDRequest(); |
| 51 | + request.CustomId = "GettingStartedGuide"; |
| 52 | + request.CreateAccount = true; |
| 53 | + |
| 54 | + FutureTask<PlayFabResult<com.playfab.PlayFabClientModels.LoginResult>> loginTask = PlayFabClientAPI.LoginWithCustomIDAsync(request); |
| 55 | + loginTask.run(); |
| 56 | + |
| 57 | + while (_running) { |
| 58 | + if (loginTask.isDone()) { // You would probably want a more sophisticated way of tracking pending async API calls in a real game |
| 59 | + OnLoginComplete(loginTask); |
| 60 | + } |
| 61 | + |
| 62 | + // Presumably this would be your main game loop, doing other things |
| 63 | + try { |
| 64 | + Thread.sleep(1); |
| 65 | + } catch(Exception e) { |
| 66 | + System.out.println("Critical error in the example main loop: " + e); |
| 67 | + } |
| 68 | + } |
| 69 | + } |
| 70 | + |
| 71 | + private static void OnLoginComplete(FutureTask<PlayFabResult<com.playfab.PlayFabClientModels.LoginResult>> loginTask) { |
| 72 | + PlayFabResult<com.playfab.PlayFabClientModels.LoginResult> result = null; |
| 73 | + try { |
| 74 | + result = loginTask.get(); // Wait for the result from the async call |
| 75 | + } catch(Exception e) { |
| 76 | + System.out.println("Exception in PlayFab api call: " + e); // Did you assign your PlayFabSettings.TitleId correctly? |
| 77 | + } |
| 78 | + |
| 79 | + if (result != null && result.Result != null) { |
| 80 | + System.out.println("Congratulations, you made your first successful API call!"); |
| 81 | + } else if (result != null && result.Error != null) { |
| 82 | + System.out.println("Something went wrong with your first API call."); |
| 83 | + System.out.println("Here's some debug information:"); |
| 84 | + System.out.println(CompileErrorsFromResult(result)); |
| 85 | + } |
| 86 | + |
| 87 | + _running = false; // Because this is just an example, successful login triggers the end of the program |
| 88 | + } |
| 89 | + |
| 90 | + // This is a utility function we haven't put into the core SDK yet. Feel free to use it. |
| 91 | + private static <RT> String CompileErrorsFromResult(PlayFabResult<RT> result) { |
| 92 | + if (result == null || result.Error == null) |
| 93 | + return null; |
| 94 | + |
| 95 | + String errorMessage = ""; |
| 96 | + if (result.Error.errorMessage != null) |
| 97 | + errorMessage += result.Error.errorMessage; |
| 98 | + if (result.Error.errorDetails != null) |
| 99 | + for (Map.Entry<String, List<String>> pair : result.Error.errorDetails.entrySet() ) |
| 100 | + for (String msg : pair.getValue()) |
| 101 | + errorMessage += "\n" + pair.getKey() + ": " + msg; |
| 102 | + return errorMessage; |
| 103 | + } |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +* Open a command window in your project folder: |
| 108 | + * Hold shift and right click in the empty-white-space of the Explorer window |
| 109 | + *  |
| 110 | + * We will use this window in the next section to execute our program |
| 111 | + |
| 112 | +Finish and Execute |
| 113 | +---- |
| 114 | + |
| 115 | +* In the command window, enter the following sequence of commands: |
| 116 | + * javac GettingStarted.java |
| 117 | + * If successful, this should finish with no output |
| 118 | + * Java -cp . GettingStarted |
| 119 | + * If successful, you should see the following text: |
| 120 | + * Congratulations, you made your first successful API call! |
| 121 | +* At this point, you can start making other api calls, and building your game |
| 122 | +* For a list of all available client API calls, see our documentation: |
| 123 | + * https://api.playfab.com/ |
| 124 | +* Happy coding! |
| 125 | + |
| 126 | +Deconstruct the code |
| 127 | +---- |
| 128 | + |
| 129 | +This optional last section describes every line in GettingStarted.java in detail. |
| 130 | + |
| 131 | +* imports |
| 132 | + * This is the minimal set of imports used to make PlayFab API calls |
| 133 | +* public static void main(String[] args) { |
| 134 | + * Just a basic loop that kicks off an API call, and waits for it to complete |
| 135 | + * PlayFabSettings.TitleId = "xxxx"; |
| 136 | + * Every PlayFab developer creates a title in Game Manager. When you publish your game, you must code that titleId into your game. This lets the client know how to access the correct data within PlayFab. For most users, just consider it a mandatory step that makes PlayFab work. |
| 137 | + * PlayFabClientModels.LoginWithCustomIDRequest request = new PlayFabClientModels.LoginWithCustomIDRequest(); |
| 138 | + * Most PlayFab API methods require input parameters, and those input parameters are packed into a request object |
| 139 | + * Every API method requires a unique request object, with a mix of optional and mandatory parameters |
| 140 | + * For LoginWithCustomIDRequest, there is a mandatory parameter of CustomId, which uniquely identifies a player and CreateAccount, which allows the creation of a new account with this call. |
| 141 | + * For login, most developers will want to use a more appropriate login method |
| 142 | + * See the PlayFab Login Documentation for a list of all login methods, and input parameters. Common choices are: |
| 143 | + * LoginWithAndroidDeviceID |
| 144 | + * LoginWithIOSDeviceID |
| 145 | + * LoginWithEmailAddress |
| 146 | + * FutureTask<PlayFabResult<com.playfab.PlayFabClientModels.LoginResult>> loginTask = PlayFabClientAPI.LoginWithCustomIDAsync(request); |
| 147 | + * This begins the async request to "LoginWithCustomID", using the Java FutureTask framework |
| 148 | + * while (running) { if (loginTask.isDone()) { OnLoginComplete(loginTask); } } |
| 149 | + * Run a trivial main loop and asynchronously wait for the loginTask to complete |
| 150 | + * When finished call OnLoginComplete |
| 151 | +* OnLoginComplete(loginTask) |
| 152 | + * result = loginTask.get(); |
| 153 | + * Fetch the async result (this won't cause a block, because we confirmed the FutureTask is already complete |
| 154 | + * if (result.Result != null), the API call is successful |
| 155 | + * When successful, result.Result object of many API callbacks will contain the requested information |
| 156 | + * LoginResult specifically contains some basic information about the player, but for most users, login is simply a mandatory step before calling other APIs. |
| 157 | + * if (result.Error != null), the API call has failed |
| 158 | + * API calls can fail for many reasons, and you should always attempt to handle failure |
| 159 | + * Why API calls fail (In order of likelihood) |
| 160 | + * PlayFabSettings.TitleId is not set. If you forget to set titleId to your title, then nothing will work. |
| 161 | + * Request parameters. If you have not provided the correct or required information for a particular API call, then it will fail. See error.errorMessage, error.errorDetails, or error.GenerateErrorReport() for more info. |
| 162 | + * Device connectivity issue. Cell-phones lose/regain connectivity constantly, and so any API call at any time can fail randomly, and then work immediately after. Going into a tunnel can disconnect you completely. |
| 163 | + * PlayFab server issue. As with all software, there can be issues. See our [release notes](https://api.playfab.com/releaseNotes/) for updates. |
| 164 | + * The internet is not 100% reliable. Sometimes the message is corrupted or fails to reach the PlayFab server. |
| 165 | + * If you are having difficulty debugging an issue, and the information within the error callback is not sufficient, please visit us on our [forums](https://community.playfab.com/index.html) |
0 commit comments