Home
The Java SDK provides an interface for the SAP Customer Data Cloud API. The library makes it simple to integrate SAP Customer Data Cloud services in your Java project.
This document is a practical step-by-step guide for programmers who wish to integrate the SAP Customer Data Cloud service into their Java project. Follow the steps below to get started, and use the Reference Library while implementing.
Follow these steps to integrate this library in your Java application.
Download the SDK JAR file from here.
Making API calls requires an API Key and a Secret Key that are obtained from the Dashboard section on the SAP Customer Data Cloud website. The Secret Key must be kept secret and never transmitted to an untrusted client or over insecure networks. The API Key and the Secret Key are required parameters in each request (further ahead in this document you will find guidance for sending requests).
The first interaction with SAP Customer Data Cloud must always be logging in. If the user is not logged in, you cannot access their social profile nor perform social activities, such as setting their status. Sending requests requires an identified SAP Customer Data Cloud user (the identification of whom is performed using the UID parameter) with an active session. A user session is created when a user logs in via the SAP Customer Data Cloud service. Log users in through your client application using our JavaScript Web SDK methods: socialize.login, socialize.notifyLogin, or using our ready made Login Add-on.
To learn more about the login process, see Social Login.
After you have logged in the user, you may use the GSRequest class to access the user profile and perform various activities, see Reference Library for more information. This is implemented using GSRequest's send method. The following code sends a request to retrieve the current user's account details.
class Program {
public static void main(String[] args) {
//Define the API-Key and Secret key (the keys can be obtained from your site setup page on Gigya's website).
final String apiKey = "PUT-YOUR-APIKEY-HERE";
final String secretKey = "PUT-YOUR-SECRET-KEY-HERE";
final String userKey = "PUT-YOUR-USER/APPLICATION-KEY-HERE";
String apiMethod = "accounts.getAccountInfo";
GSRequest request = new GSRequest(apiKey, secretKey, apiMethod, null, true, userKey);
request.setParam("UID","Enter-A-Valid-UID-Here");
request.setParam("include","identities-active,identities-all,identities-global,loginIDs,emails,profile,data, password,lastLoginLocation, regSource,irank,rba,subscriptions,userInfo");
request.setParam("extraProfileFields","languages,address,phones, education, honors, publications, patents, certifications, professionalHeadline, bio, industry, specialties, work, skills, religion, politicalView, interestedIn, relationshipStatus, hometown, favorites, followersCount, followingCount, username, locale, verified, timezone, likes, samlData");
GSResponse response = request.send();
if(response.getErrorCode()==0)
{
System.out.println("success!");
}
else
{
System.out.println("Uh-oh, we got the following error: " + response.getLog());
}
}
}
Create a GSRequest instance:
GSRequest request = new GSRequest(apiKey, secretKey, apiMethod, null, true, userKey);
The parameters of the GSRequest constructor are:
- apiKey
- secretKey - The secret that corresponds to the userKey used in the request
- method - the SAP Customer Data Cloud API method to call, including namespace. For example: 'socialize.getUserInfo'. Refer to REST API reference for the list of available methods.
After creating the GSRequest object, use the setParam method to add parameters to the request:
request.setParam("param2", "value2");
request.setParam("param3", "value3");
...
When a parameter is a complex object, use the GSObject class. See example in the Appendix below.
Note In the REST API reference you may find the list of available SAP Customer Data Cloud API methods and the list of parameters per method.
Execute GSRequest's send method:
GSResponse response = request.send();
The method returns a GSResponse object, which is handled in the next step.
Note By default, requests to the SAP Customer Data Cloud API are sent using the "us1.gigya.com" domain. If your site has been set up to use another of SAP Customer Data Cloud's data centers, you must specify that the request should be sent to that specific data center and add the following line of code before calling the Send method:
request.setAPIDomain("<Data_Center>");If you are not sure of your site's data center, see Finding Your Data Center.
See the Reference Library documentation for more information.
Use the GSResponse object to check the status of the response, and to receive response data:
if (response.getErrorCode() == 0) { // SUCCESS! response status = OK
System.out.println("Success in setStatus operation.");
} else { // Error
System.out.println("Got error on setStatus: " + response.getLog());
}
The GSResponse object includes data fields. For each request method, the response data fields are different. Refer to REST API reference for the list of response data fields per method.
For example - handling a socialize.getUserInfo response:
The response of 'socialize.getUserInfo' includes a 'user' object.
// Sending 'socialize.getUserInfo' request
GSRequest request = new GSRequest(apiKey, secretKey, "socialize.getUserInfo", false);
request.setParam("uid", "PUT-UID-HERE"); // set the "uid" parameter to user's ID
GSResponse response = request.send();
// Handle 'getUserInfo' response
if (response.getErrorCode() == 0) {
// SUCCESS! response status = OK
String nickname = response.getString("nickname", "");
int age = response.getInt("age", 0);
System.out.println("User name: " + nickname + "; The user's age: " + age);
} else {
System.out.println("Got error on getUserInfo: " + response.getLog());
}
Signature validation is only necessary and supported when validating the signature of a response that was received on the client side and then passed to the server. Server-to-server calls do not contain the UIDSignature or signatureTimestamp properties in the response.
The SAP Customer Data Cloud service supports a mechanism to verify the authenticity of the SAP Customer Data Cloud processes, to prevent fraud. When SAP Customer Data Cloud sends you information about a user, your server needs to know that it is actually coming from SAP Customer Data Cloud. For this reason, SAP Customer Data Cloud attaches a cryptographic signature to the responses that include user information. We highly recommend validating the signature. The SigUtils class is a utility class for generating and validating signatures.
For example, SAP Customer Data Cloud signs the socialize.getUserInfo method response. The following code validates the signature received with the 'socialize.getUserInfo' method response:
// Handle 'getUserInfo' response
if (response.getErrorCode() == 0) {
// SUCCESS! response status = OK
// Validate the signature
bool valid = SigUtils.validateUserSignature(response.getString("UID", ""), response.getString("signatureTimestamp", ""),
secretKey, response.getString("UIDSignature", ""));
if (valid)
System.out.println("signature is valid");
else
System.out.println("Fraud!!!");
}
The parameters of the validateUserSignature method are:
- UID - the user's unique ID
- signatureTimestamp - The GMT time of the response in UNIX time format (i.e. the number of seconds since Jan. 1st 1970). The method validates that the timestamp is within five minutes of the current time on your server.
- secretKey - The key to verification is your partner's "Secret Key". Your secret key (provided in BASE64 encoding) is located at the bottom of the Dashboard section on SAP Customer Data Cloud's website (Read more above).
- UIDSignature - the cryptographic signature.
All the parameters, with the exception of the secretKey, should be taken from the 'User' object received with the 'getUserInfo' method response.
The method returns a Boolean value, signifying if the signature is valid or not.
In a similar fashion, when using the 'getFriendsInfo' method, the method response includes a collection of 'Friend' objects. Each Friend object will be signed with a cryptographic signature. To verify the signature of a friend object, use the validateFriendSignature method.
To send requests to the SAP Customer Data Cloud service using SSL, set the request to use HTTPS:
When creating a GSRequest object, set the useHTTPS Boolean parameter to be true.
boolean useHTTPS = true; // send the request over HTTPS
GSRequest request = new GSRequest(apiKey, secretKey, method, useHTTPS);