Miscellaneous

Error handling

Android SDK has a wrapper called ApiError to help you handle errors within your app. These errors are normally returned back from our RESTful API methods that SDK implements.

When a Throwable instance is passed to create ApiError wrapper, you can get the following information:

apiError.getThrowable()

Returns the original Throwable instance. May be null if ApiError was instantiated with the ApiError(Response) constructor.

apiError.printStackTrace()

Prints the stack trace of the original Throwable instance.

apiError.getHttpCode()

Returns the HTTP status code. If request failed to execute (for example, due to no Internet connection), this value will be equal -1.

apiError.getErrorType()

ErrorType.HTTP_ERROR is returned when the request succeeded to execute, but something went wrong and an error code is returned (e.g. 403).
ErrorType.NETWORK_ERROR is returned when the request failed to execute (for example, due to no Internet connection).
ErrorType.UNKNOWN is returned when an unknown error occurred (for example, no response form server when expected).

apiError.getHttpErrorCategory()

Returns the mapped response’s HTTP code (for example, HTTP 400 code will be mapped to HttpErrorCategory.BAD_REQUEST, or 403 to HttpErrorCategory.FORBIDDEN).

apiError.getErrorBody()

Returns the ApiErrorBody parsed from the response’s error body. May be null if error type is different than ErrorType.HTTP_ERROR.

Sample usage

When you receive an error, you can check if the error is ApiError and then, you can get more information and a list of all errors that occurred. In result, you can better integrate your own application with the Synerise SDK.

The following sample code shows a way to handle API errors:

private void showAlertError(ApiError apiError) {
    ApiErrorBody errorBody = apiError.getErrorBody();
    int httpCode = apiError.getHttpCode();
    // create AlertDialog with icon and title
    AlertDialog.Builder dialog = new AlertDialog.Builder(this).setIcon(R.drawable.sygnet_synerise);
    if (httpCode != ApiError.UNKNOWN_CODE) {
        dialog.setTitle(String.valueOf(httpCode));
    } else {
        dialog.setTitle(R.string.default_error);
    }
    // append all available messages from API
    if (errorBody != null) {
        List<ApiErrorCause> errorCauses = errorBody.getErrorCauses();
        StringBuilder message = new StringBuilder(errorBody.getMessage());
        if (!errorCauses.isEmpty())
            for (ApiErrorCause errorCause : errorCauses)
                message.append("\n").append(errorCause.getCode()).append(": ").append(errorCause.getMessage());
        dialog.setMessage(message.toString());
    // if there is no available messages, set default one
    } else {
        switch (apiError.getErrorType()) {
            case HTTP_ERROR:
                if (apiError.getHttpErrorCategory() == UNAUTHORIZED) {
                    dialog.setMessage(getString(R.string.error_unauthorized));
                } else {
                    dialog.setMessage(getString(R.string.error_http));
                }
                break;
            case NETWORK_ERROR:
                dialog.setMessage(getString(R.string.error_network));
                break;
            default:
                dialog.setMessage(getString(R.string.error_default));
        }
    }
    // show dialog
    dialog.show();
}

That’s just a suggestion on how to implement errors exposed by the SDK. You can implement your own solution.

ApiErrorBody provides attributes such as error, message, path, status and list a of causes, errors.
ApiErrorCause provides attributes such as field, code, message, rejectedValue.

Crash handling

Crash handler allows you to find customers whose mobile applications crashed and to see information about that in their customer cards in Profiles as events.
The crash is connected with a customer. Using the data from our crash handler, you can send a personalized apology when the application crashes.

Configuration

You can enable crash handling for Synerise SDK by using the Synerise.crashHandlingEnabled(true) method.

When it is enabled, the Synerise SDK passes info about customer application crashes as dedicated events to the backend (client.applicationCrashed is the action parameter of those events).

Silent SDK Commands

Silent location command

To request location, let your application class implement OnLocationUpdateListener and also provide it to Synerise Builder.

public class App extends MultiDexApplication implements OnLocationUpdateListener {
    private static final String TAG = App.class.getSimpleName();
    @Override
    public void onCreate() {
        super.onCreate();
         Synerise.Builder.with(this, syneriseClientApiKey, appId)
                                .notificationIcon(R.drawable.ic_notification_icon)
                                .locationUpdateRequired(this)
                                ...
                                .build();
    }
    @Override
    public void onLocationUpdateRequired() {
        // your logic here
    }
}

Now, anytime you send the below frame from app.synerise.com, your application will receive the callback onLocationUpdateRequired, from which your app can get device location. For example implementation, check our sample application.

"data": {
    "issuer": "Synerise",
    "message-type": "dynamic-content",
    "content-type": "silent-sdk-command",
    "content": {
        "class_name": "com.synerise.sdk.injector.Injector",
        "method_name": "GET_LOCATION",
        "method_parameters": []
    }
}

Note that incoming silent push command will awake or launch your application in the background, which causes SDK initialization (if not already initialized).
It means, for instance, that AppStartedEvent will be sent and/or banners will be fetched.
In addition, the location event may be sent automatically on demand. This is done with the Synerise.locationAutomatic(boolean) initialization method.
For custom implementation, remember to send AppearedInLocationEvent in the onLocationUpdateRequired callback.

Note:

Synerise SDK asks for the ACCESS_FINE_LOCATION permission. To remove this permission from your application, include the following line in your AndroidManifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>

Silent sign out command

To force a sign out, send a silent push to the target device.

Note: This mechanism should be used only in specific situations, not as a standard solution.

When you send the below frame from app.synerise.com, the SDK will clear a customer’s token and sign them out.

"data": {
    "issuer": "Synerise",
    "message-type": "dynamic-content",
    "content-type": "silent-sdk-command",
    "content": {
        "class_name": "com.synerise.sdk.injector.Injector",
        "method_name": "SIGN_OUT",
        "method_parameters": []
    }
}

Note that an incoming silent push command awakes or launches your application in the background, which causes SDK initialization (if not already initialized).
It means, for example, that AppStartedEvent will be sent and/or banners will get fetched.

Cache manager

Cache manager provides you with an easy-to-use option to retrieve cached data (if available) if communication problems with the backend occur.

If a request fails, you can obtain the cached data by using CacheManager as follows:

YourClass cachedModel = (YourClass) CacheManager.getInstance().get(YourClass.class);

Currently, our Cache Manager supports the caching of GetAccountInformation after a successful Client.getAccount() response.