Integrating with Fyber’s Virtual Currency Server (VCS)

If you don’t host your own currency service, Fyber provides virtual currency hosting. This is the default setting for mobile applications on your developer dashboard.

Request for New Coins

To perform this request, call the following static method:

VirtualCurrencyRequester.create(virtualCurrencyCallback)
        .request(activity);

This method will return the delta of coins for your default currency.

This method takes the following parameters and expects that you’ve already created credentials (with the Fyber.with method.

VirtualCurrencyCallback is an object implementing the VirtualCurrencyRequester interface which will be notified of the result of the request (see below for a description of this interface). There are three methods:

  • onRequestError
  • onSuccess
  • onError

Each method call can be seen in the snippet below:

VirtualCurrencyCallback virtualCurrencyCallback = new VirtualCurrencyCallback() {
    @Override
    public void onRequestError(RequestError requestError) {
        Log.d(TAG, "request error: " + requestError.getDescription());
    }

    @Override
    public void onSuccess(VirtualCurrencyResponse virtualCurrencyResponse) {
        // Process the deltaOfCoins in the way that makes most sense for your application
        double deltaOfCoins = virtualCurrencyResponse.getDeltaOfCoins();
    }

    @Override
    public void onError(VirtualCurrencyErrorResponse virtualCurrencyErrorResponse) {
        Log.d(TAG, "VCS error received - " + virtualCurrencyErrorResponse.getErrorMessage());
    }
};

If your application contains multiple currencies then you have to use the static method to chain an extra method to your string:

VirtualCurrencyRequester.create(virtualCurrencyCallback)
    .forCurrencyID(for multiple currency IDs)
    .request(activity);

Then specify the id of the currency that you want to receive.

Full Request Process

The full request process for using VCS is:

VirtualCurrencyCallback virtualCurrencyCallback = new VirtualCurrencyCallback() {
    @Override
    public void onRequestError(RequestError requestError) {
        Log.d(TAG, "request error: " + requestError.getDescription());
    }

    @Override
    public void onSuccess(VirtualCurrencyResponse virtualCurrencyResponse) {
        // Process the deltaOfCoins in the way that makes most sense for your application
        double deltaOfCoins = virtualCurrencyResponse.getDeltaOfCoins();
    }

    @Override
    public void onError(VirtualCurrencyErrorResponse virtualCurrencyErrorResponse) {
        Log.d(TAG, "VCS error received - " + virtualCurrencyErrorResponse.getErrorMessage());
    }
};

VirtualCurrencyRequester.create(virtualCurrencyCallback)
    .request(activity);

Toast Notifications

A toast notification will be shown by default after a successful request in which the delta of coins is bigger than 0. When the Fyber SDK is first started, you receive a settings object that you can then use to customize the toast notifications. You can specify two different toast notification types:

Fyber.Settings settings = Fyber.with(appId, this).start();
settings.notifyUserOnCompletion(true)
    .notifyUserOnReward(true);
  • notifyUserOnCompletion is the toast after watching the video which states you will be rewarded soon
  • notifyUseronReward is the toast stating the amount of coins earned. The toast notification will show Congratulations! You’ve earned XX coins!

You can customize the default message four different ways:

settings.setCustomUIString(Fyber.Settings.UIStringIdentifier.VCS_COINS_NOTIFICATION, "NEW CUSTOM MESSAGE %.0f %s");

Note that the message needs to contain two placeholders:

  • The first one (%.0f) for the amount of currency earned,
  • The second (%s) for the currency name (see above).

Adding Custom Parameters for VCS

If you are interested in adding a custom parameter to your Android SDK Virtual currency request, you can pass along custom parameters in this way:

// creating a map of parameters to be used with a specific offer wall requester
Map mapOfParameters = new HashMap<String,String>();
mapOfParameters.put("key1", "value1");
mapOfParameters.put("key2", "value2");

VirtualCurrencyRequester virtualCurrencyRequester = VirtualCurrencyRequester.create(virtualCurrencyCallback);
//adding a custom parameter to be used with this offer wall requester
virtualCurrencyRequester.addParameter("key3", "value3")
//adding a list of custom parameters to be used in this offer wall requester
        .addParameters(mapOfParameters);

Response

The VirtualCurrencyRequester method returns immediately, and the actual request to the server is performed on a background thread. To be notified of the response, you must provide a listener object which implements the VirtualCurrencyCallback interface. Your implementation of this interface will be invoked back on the UI thread. The interface contains just two methods, one invoked if the request succeeded and the server returned an answer, and the other invoked in case of error:

  • onSuccess(VirtualCurrencyResponse virtualCurrencyResponse)

is called with the answer returned from the server if no error is triggered. The passed response parameter contains the response data. Use onSuccess(VirtualCurrencyResponse virtualCurrencyResponse) to obtain the number of coins the user has earned since the last request to VCS and response.getLatestTransactionId() if you’re interested in the user’s latest transaction ID.

The passed response parameter returned from first call to VCS from a new installation of your app will always contain the reward amount and transaction ID of the user’s latest transaction in our system. To avoid rewarding a user for a second time in case that they have uninstall and re-install your app, you can do one of two things:

Option 1: Store it

Store the most recent transaction ID somewhere that will survive an uninstall, and compare it to the transaction ID returned from response.getLatestTransactionId(). Only rewarding when the stored ID and returned ID don’t match.

Option 2: Fresh install

Ignore the first response from VCS from a fresh install of your app. All subsequent calls to VCS will then behave normally.

Error Types

onError(VirtualCurrencyErrorResponse virtualCurrencyErrorResponse) is invoked either if the request fails or the server returns an error. The provided response parameter has two error types to determine the cause of the error:

  • response.getError() returns the general type of the error, defined in the getError enum type. A description of the possible error types is shown below.
  • response.onRequestError will return exact the server-provided error code and error message. This methods will only return meaningful data if the error type is ErrorType.SERVER_RETURNED_ERROR, as will be described in the table below.

Defined in VirtualCurrencyErrorResponse.ErrorType, obtained via response.getErrorType()

Error type Description
ERROR_INVALID_RESPONSE Returned response is not formatted in an expected way.
ERROR_INVALID_RESPONSE_SIGNATURE Response doesn’t contain a valid signature. The response signature is verified against your secret token.
SERVER_RETURNED_ERROR The server returned an error. Use response.getErrorCode() and response.getErrorMessage().
ERROR_OTHER An error occured whose cause couldn’t be determined.

Note: If the userId is changed after an offer is requested but before it’s completed, upon completion of that offer the rewarded User will be the one active by the time of the request.