/
Nutaku Game Platform REST API (Native SDK)

Nutaku Game Platform REST API (Native SDK)

Owned by Nutaku Staff
Jun 03, 2024

This page refers to Nutaku SDK 3.0.0+. For Older SDK versions please consult the page history.

The SDK has methods that allows easy usage of the "Nutaku Game Platform REST API".

For details about each API, refer to "Nutaku Game Platform REST API Reference" (Hereafter, called API Reference).

NutakuApi class is part of the SDK's package com.nutaku.game.sdk.osapi.


Note: to keep the sample code simple to understand, from section 3 onwards, error handling is not included in the sample code. Make sure you add error handling as described in sections 1 and 2 yourself!


1. Error Handling

You can know if an error occurred by checking the response code. Refer to the API Reference for response code details in each API.

You can also check the isSuccess() method on the response object.

Sample

NutakuPeopleRequest req = NutakuApi.requestProfile();
NutakuPeopleResponse res = req.execute();

if (res.isSuccess()) {
    // Success
} else {
    int responseCode = res.getResponseCode();
    if (responseCode = 400) {
        // handle Bad Request
    } else if (responseCode = 401) {
        // handle OAuth Failure
    }
}

2. Retry

If you receive a communication error (IOException), it’s recommended that you retry up to 3 times before handling it as an error

Sample

NutakuPeopleRequest req = NutakuApi.requestProfile();

try {
    NutakuPeopleResponse res = req.execute();
} catch (IOException e) {
    // Retry processing for communication error, up to 3 times, before handling it as an actual error
}

// response analysis if retrying was successful

3. People API

This is an API to get user profile information and follower list.

Profile and follower list information can be retrieved by using the classes "NutakuPeopleRequest" and "NutakuPeopleResponse". For possible fields to retrieve, refer to NutakuPerson in the SDK reference.

Note that if you only need the ID of the current player, you can access it directly via NutakuUserInfo.getUserId(), no need to make API calls.

3.1. Retrieving profile information for the current player

Sample

NutakuPeopleRequest req = NutakuApi.requestProfile();
NutakuPeopleResponse res = req.execute();

NutakuPerson profile = res.getPersons().get(0);
log("User Id: " + profile.getId());
log("Nickname: " + profile.getNickname());　

3.2. Retrieving profile information for other players

Sample

NutakuPeopleRequest req = NutakuApi.requestPerson(someOtherPlayerIdAsString);
NutakuPeopleResponse res = req.execute();

NutakuPerson profile = res.getPersons().get(0);
log("User Id: " + profile.getId());
log("Nickname: " + profile.getNickname());


4. Payment API

Payment API is an API to perform a purchase processing when a user purchases items in-game. A Payment ID is issued by the API Server and you can manage/process by using that ID throughout the payment flow. The payment flow is presented elsewhere in the documentation.

4.1. Payment Creation request

Sample

NutakuPayment payment = new NutakuPayment();
payment.setCallbackUrl("http://example.com/callback"); //Please be aware that your payment handler url must have at least one slash after the domain. Invalid: "https://example.com". Valid "https://example.com/", "https://example.com/examplepath"
payment.setMessage("Test Payment"); // we recommend leaving this blank and using the Name and Description fields from the item definition. This field is no longer shown to the user.

NutakuPaymentItem item = new NutakuPaymentItem();
item.setItemId("ex101");
item.setItemName("Item 1");
item.setUnitPrice(10);
item.setImageUrl("http://example.com/ex101.jpg");
item.setDescription("Item 1 description");
payment.setPaymentItem(item);

NutakuPaymentRequest req = NutakuApi.postPayment(payment);
NutakuPaymentResponse res = req.execute();

NutakuPayment processedPayment = res.getPayment();
log("------------");
log("app ID: " + processedPayment.getAppId());
log("payment ID: " + processedPayment.getPaymentId());
log("status: " + TestUtil.getPaymentStatusName(payment.getStatus())); //this  function is in the Sample Application code that ships with the SDK
log("message: " + processedPayment.getMessage());
log("order date and time: " + processedPayment.getOrderedTime());
log("payment date and time: " + processedPayment.getExecutedTime());
log("\t item name: " + processedPayment.getPaymentItem().getItemName());
log("\t quantity: " + processedPayment.getPaymentItem().getQuantity());
log("\t unit price: " + processedPayment.getPaymentItem().getUnitPrice());
log("\t description: " + processedPayment.getPaymentItem().getDescription());

4.2. Display the item purchase page (transactionUrl)

Retrieves the transactionUrl (html page where the user confirms the purchase) from the payment creation response, and displays the payment page.

Sample

NutakuPaymentResponse res = req.execute();
NutakuPayment processedPayment = res.getPayment();
processedPayment.openTransactionDialog(context);


5. makeRequest API

This is an API that allows for communication to your server through the Nutaku server which adds OAuth RSA signature for security.

Calling an example endpoint with post data and custom query parameters. For more details, check the PostMakeRequestTestTask class from the Sample Application.

IMPORTANT: if you intend to use this feature to send non-alphanumeric characters (like the user's display name which can contain spaces or non-latin characters), it will break the RSA signature. To prevent this, you can first do a base64 encoding of the value before sending it over as a parameter to makeRequest.

WARNING: this feature is intended to be used for exchanging simple data, such as parameters and tokens for the purpose of authentication initialization. Do not use this for regular communication with your game server, because it will cause delay. You should also not use this as mechanism to transfer large amounts of data, because the timeout will force stop the request after 5 seconds (which includes network latency).

CRITICAL: any user with a modded browser or a modded APK can alter the data you send to this feature, therefore you must not important like the user id as a custom parameter because the malicious user can change it and it will impersonate some other player. For handshake purposes you should read the opensocial_owner_id parameter that the platform automatically adds server-side before calling your destination endpoint.

Sample

//HashMap<String, String> postData = new HashMap<>();
//postData.put("post_data_example", "1");
//NutakuMakeRequest req = NutakuApi.postMakeRequest("https://api.example.com/test?example_param=2", postData);
// using the above 3 lines will cause a POST request to your endpoint. We recommend you do not use that approach, just use the below simple call. Note that it will call your server with GET in this way, not a post.
NutakuMakeRequest req = NutakuApi.postMakeRequest("https://api.example.com/test?example_param=2", null);
NutakuMakeResponse res = req.execute();
log("HTTP Response code (from Nutaku API): " + res.getResponseCode());
if (res.isSuccess()) {
    log("result code from destination API: " + res.getDestinationResponseCode());
    log("body: "+ res.getResponseFromDestination());
}


Related content