Follow

Shape Defense Mobile SDK Android Reference

The Mobile SDK for Android consists of one main class: APIGuard

Package namespace: com.apiguard3

 

System Requirements

  • Android Studio

API levels:

  • Fully supported: Android 4.4/API 19 and newer

  • Compatible with: Android 4.1/API 16 and newer

Library Required:

  • OkHttp3
Note: Mobile SDK supports OkHttp version 3.12 LTS and is compatible with 3.7, 3.10, 3.12, 3.14, and 4.3.1. Please be aware that different OkHttp versions have different minimum Android OS and Java version requirements.

Permissions Required:

  • android.permission.INTERNET
  • android.permission.ACCESS_NETWORK_STATE

These permissions are likely already present and must not be removed.

 

Public Classes

The Mobile SDK Android has the following public classes:

Class
APIGuard
Description
This is the main class that implements the interface with the application. APIGuard is an interface between the host app and Mobile SDK. It lets the host app communicate and manage the SDK, including SDK initialization and transforming requests and responses.
Methods

 

Method

initialize

Syntax
public void initialize(@NonNull final Application application, @NonNull Callback callback, @RawRes int resId, @Nullable String environment)
Description
This method initializes Mobile SDK with the application object, Callback object, and an ID of the raw resource bundled in the app.
Parameters
application The application object of the host app.
callback An object that implements Callback interface.
resId ID of the raw resource that contains the base kernel configurations.
environment A string value that specifies the environment to use for requesting updates. This parameter can be null.
initialize

Performs initialization of Mobile SDK in the background. The getRequestHeaders method proceeds without waiting for initialize to complete, if it's called very soon after initialize. The API doesn't throw an error, but the request object isn't decorated.

To avoid the empty decoration of the request, Shape recommends providing time between calls to initialize and getRequestHeaders. For example, if you have an auto-login on app launch, call initialize in your Application class's onCreate() and call getRequestHeaders as the last method in your Activity's onCreate.

Example:

In your Application class, in the onCreate() method call:

APIGuard.getSharedInstance().initialize(this, this, R.raw.apiguard, "QA")

 

Method

transformRequest (Deprecated in version 4.0.0. Will not be available in future versions of Mobile SDK.)

Syntax
void transformRequest(AGRequest request) throws NotReadyException
Description
This function transforms the outgoing network request by adding Mobile SDK payload (headers) to the request for the host app to process.
Parameters
request A Mobile SDK request object that decorated with a Mobile SDK payload.

 

Method

parseResponse (Deprecated in version 4.0.0. Will not be available in future versions of Mobile SDK.)

Syntax
void parseResponse(AGResponse response) throws NotReadyException
Description
This function parses the incoming API response from the Shape Defense EngineThe traffic processor and AI that power Shape Enterprise Defense. The defense engine uses policies and TI packages to identify bad actors. for internal configuration management functionality. It can also trigger a configuration update caused by specific parts of the response.
Parameters
response The AGResponse object that represents the Mobile SDK transformed response to the app.

  

Method

getState

Syntax
AGState agState = apiGuard.getState();
Description

This method returns the current state of the APIGuard. The value is an enum object of type AGState, with four possible states:

  1. APIGuardStateNotReady - initialize() was not yet called
  2. APIGuardStateInProgress - initialize() was called, but did not finish
  3. APIGuardStateReady - APIGuard is ready
  4. APIGuardStateFailed - initialize() was called, but initialization failed
Example
if (apiGuard.getState() == AGState.APIGuardStateReady) {
Log.d("AGState", "READY");
}

 

 

Method

getRequestHeaders

Syntax
Map<String, String> requestHeaders = APIGuard.getSharedInstance().getRequestHeaders("https://example.com", null);
Description
This method generates APIGuard-specific headers that should be attached to the network request.
Parameters
url The full URL of the request.
body The body of the request.
Returns
The map of HTTP headers to add to the request.

 

Method

parseResponseHeaders

Syntax
APIGuard.getSharedInstance().parseResponseHeaders(responseHeaders)
Description
This function parses the APIGuard-specific response headers returned to the app from the origin and takes appropriate actions.
Parameters
headers Map of the HTTP response headers.

 

Class
Callback
Description
This interface defines methods for a callback interface that must be implemented by the host application for Mobile SDK to call.
Methods

 

Method
checkCertificates
Syntax
void checkCertificates(List<Certificate> certificates, String host) throws IOException
Description

The checkCertificates method requests that the host app verify the provided certificates and host. If the certificates seem invalid, an exception is thrown.

Mobile SDK calls this method when connection is being established to update the configuration file.

Note: Shape Security recommends using the checkCertificates method whenever possible.
Parameters
certificates Certificate(s) to be verified for connection.
host Host portion of the URI.
Errors
IOException Throw an ioException if the connection’s certificate does not match pinned certificates.

 

Method

log

Syntax
void log(String message)
Description
Mobile SDK calls the log method when it needs to log a message to the host app for debugging purposes. The messages are intended for developers; do not log them to the system log in production apps.
Parameters
message Message for the host app to log.

 

Class
InitializationCallback
Description
These callbacks extend the Callback interface.
Callbacks

 

Callback

onInitializationSuccess

Syntax
public void onInitializationSuccess()
Description
This callback gets called on APIGuard initialization success. Mobile SDK will call this method on a background thread.
Parameters
None.
Example
public void onInitializationSuccess() {
  Log.d("AG Initialization Success");
}

 

Callback

onInitializationFailure

Syntax
public void onInitializationFailure(String failureReason)
Description

This callback gets called if initialization for APIGuard failed. The failure reason is passed as a string. This function is called on a background thread.

Initialization may fail due to improper base configuration or critical non-recoverable errors. Please contact your Shape Technical Account Manager (TAM) for additional support.

Parameters
String Failure reason.
Example
public void onInitializationFailure(String failureReason) { Log.d("AG Initialization Failed", failureReason); }

 

AGRequest class

(Deprecated in Mobile SDK version 4.0.0.)

AGRequest is a wrapper object for the request object of the networking library. This object maintains  the properties of the request.

AGRequest's Builder Class helps to build the AGRequest object. It translates an HTTP request object to AGRequest. It can convert a request object from any networking library that you use to an AGRequest.

Class
AGRequest
Syntax
AGRequest(Builder requestBuilder)
Description

A constructor to build the AGRequest object from the corresponding object.

Parameters
requestBuilder The Builder that carries the properties of a networking object.

 

AGRequest methods

getUrl

Getter for the URL of the request.

getMethod

Getter for the HTTP method of the request.

getHeaders

Getter for the headers of the request.

getBody

Getter for the body of the request.

newBuilder

Method to call to add or modify any properties of an AGRequest object.

 

Method
getUrl
Syntax
public String getUrl()
Description
Getter for the URL of the request.
Parameters
None.
Returns
The URL of the request.
 
Method
getMethod
Syntax
public String getMethod()
Description
Getter for the HTTP method of the request.
Parameters
None.
Returns
The method of the request.

 

Method
getHeaders
Syntax
public Map<String, String> getHeaders()
Description
Getter for the headers of the request.
Parameters
None.
Returns
A map of headers associated with the request.

 

Method
getBody
Syntax
public byte[] getBody()
Description
Getter for the body of the request.
Parameters
None.
Returns
The request body, as a byte array.

 

Method
newBuilder
Syntax
public Builder newBuilder()
Description
Method to call to add or modify any properties of an AGRequest object.
Parameters
None.
Returns
Builder object populated with the properties of the current object.

 

Builder class

AGRequest's Builder Class helps to build the AGRequest object. It translates an HTTP request object to AGRequest. It can convert a request object from any networking library that you use to an AGRequest.

Builder methods

Method Description
url Sets the URL target.
method Sets the method.
get Sets the method to GET and body to null.
head Util method to set up with HEAD method and body to null.
delete Util method to set up with DELETE method and body to null.
post Util method to set up with POST method and body.
put Util method to set up with PUT method and body.
addHeader Setter method to add a header to the builder header map.
headers Setter method to add a map of headers to the request.
headersMultiMap Setter method to add a multiMap of headers to the request.
 
Method
url
Syntax
public Builder url(String url)
Description
Sets the URL target.
Parameters
url The target URL.
Returns
Builder with the URL populated.

 

Method
method
Syntax
public Builder method(String method, byte[] body)
Description
Sets the method.
Parameters
method The HTTP method.
body The body, translated to a byte array.
Returns
Builder with the HTTP method and body populated.

 

Method
get
Syntax
public Builder get() {}
Description
Sets the method to GET HTTP and the body to null.
Parameters
None.
Returns
Builder object set up with the GET method.

 

Method
Syntax
public Builder head() {}
Description
Sets the method to HEAD HTTP and the body to null.
Parameters
None.
Returns
Builder object set up with the HEAD method.

 

Method
delete
Syntax
public Builder delete()
Description
Sets the method to DELETE HTTP and the body to null.
Parameters
None.
Returns
Builder object set up with the DELETE method.

 

Method
post
Syntax
public Builder post(byte[] body)
Description
Sets the method to POST HTTP method and the body.
Parameters
None.
Returns
Builder object set up with the POST method and body.

 

Method
put
Syntax
public Builder put(byte[] body) {}
Description
Sets the method to PUT HTTP method and the body.
Parameters
None.
Returns
Builder object set up with the PUT method and body.

 

Method
addHeader
Syntax
public Builder addHeader(String name, String value)
Description
Adds a header to the Builder header map.
Parameters
name Name of the header to add to the map.
value Value of the header.
Returns
Builder object with those headers added.

 

Method
headers
Syntax
public Builder headers(Map<String, String> requestHeaders)
Description
Adds a map of headers.
Parameters
requestHeaders Map of headers to add.
Returns
Builder with requestHeaders added.

 

Method
headersMultiMap
Syntax
public Builder headersMultiMap(Map<String, List<String>> headersMultiMap)
Description
Adds a multiMap of headers.
Parameters
headersMultiMap A multiMap of headers to add.
Returns
Builder with headersMultiMap added. Headers are combined to reduce a multiMap to a map.

 

AGResponse

(Deprecated in version Mobile SDK 4.0.0.)

This builder class translates an HTTP response object to AGResponse. This class can convert a response object from any networking library to an AGResponse.

AGResponse is a wrapper object for the response object of the networking library. This object maintains all the properties of the response.

AGResponse's Builder Class helps to build the AGResponse object. It translates an HTTP response object to AGResponse. It can convert a response object from any networking library to an AGResponse.

Class
AGResponse
Syntax
AGResponse(Builder responseBuilder)
Description
A constructor to build the AGResponse object from the corresponding builder object.
Parameters
responseBuilder The Builder that carries all the properties of a networking object.

 

AGResponse methods

getUrl

Getter for the URL of the response.

getMethod

Getter for the HTTP method of the response.

getStatusCode

Getter for the response status code.

getHeaders

Getter for the headers of the response.

 

Method
getUrl
Syntax
public String getUrl()
Description
Getter for the URL of the response.
Parameters
None.
Returns
The URL of the response.
 

 

Method
getMethod
Syntax
public String getMethod()
Description
Getter for the HTTP method of the response.
Parameters
None.
Returns
The method of the response.
 

 

Method
getStatusCode
Syntax
public int getStatusCode()
Description
Getter for the response status code.
Parameters
None.
Returns
The status code.
 

 

Method
getHeaders
Syntax
public Map<String, String> getHeaders()
Description
Getter for the headers of the response.
Parameters
None.
Returns
A map of headers associated with the response.

 

Builder class

The Builder class for AGResponse is the same as the Builder class for AGRequest.

 

Appendix: checkCertificates code sample

The following code snippet uses the CertificatePinner API of OkHttp to validate the pinned public key for a configured domain.

Note: This is an example of verifying the public key pinning for Shape Mobile SDK configuration fetch. Please make sure to conform to your organization’s security policies/requirements.
@Override
public void checkCertificates(List list, String s) throws IOException {

        String domainName = "mobile-test.fastcache.net";

        CertificatePinner certificatePinner = new CertificatePinner.Builder()
                .add(domainName, "sha256/4j+7QhRAg9xZaevlP3wQ7jvzsjYBuMidlVD83dl3d54=")
                .add(domainName,"sha256/5kJvNEMw0KjrCAu7eXY5HZdvyCS13BbA0VJG1RSP91w=")
                .add(domainName, "sha256/r/mIkG3eEpVdm+u/ko/cwxzOMo1bk4TyHIlByibiA5E=")
                .build();

        certificatePinner.check(domainName, list);
  }

 

Related Content

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request