# Server Side Rewarding

Providing incentives for app users is a great way of encouraging customer engagement with your app. With Rewarded Ads, incentives come in the form of in-app rewards that are offered to users in exchange for watching a video ad in full.

To enable Server Side Rewarding you must first integrate rewarded ads. For more information, see [Rewarded Ads](https://docs.digitalturbine.com/dt-fairbid/fairbid-sdk/ad-formats/rewarded-ads).

## Initializing the SDK <a href="#id-01h8xqfjpzdtcejxapz3b9rbd9" id="id-01h8xqfjpzdtcejxapz3b9rbd9"></a>

When initializing the SDK, there are no changes to be taken into consideration. The rewarded ad completion itself triggers Server Side Rewarding. However, you must make sure the User ID is set before this action happens. It can be set before or after initialization of the SDK.

### Setting the User ID <a href="#id-01h8xqfjpzrrkztdermak5f8br" id="id-01h8xqfjpzrrkztdermak5f8br"></a>

Implement according to the correct operating system to set the User ID.

{% tabs %}
{% tab title="Android" %}
{% code title="C#" %}

```csharp
UserInfo.setUserId("myUserId");
```

{% endcode %}
{% endtab %}

{% tab title="iOS" %}
{% code title="obj-c" overflow="wrap" %}

```objective-c
FYBUserInfo *userInfo = [FairBid user]; userInfo.userId = @"myUserId";
```

{% endcode %}

{% code title="Swift" %}

```swift
let userInfo = FairBid.user() userInfo.userId = "myUserId"
```

{% endcode %}
{% endtab %}

{% tab title="Unity" %}
{% code title="C#" %}

```csharp
UserInfo.SetUserId("myUserId");
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The User ID length must not exceed 256 characters. If it does, the Server Side Reward callback will not contain a User ID value.
{% endhint %}

If no User ID is set, the DT FairBid SDK uses one of the following identifiers:

* The IDFV, for an iOS device.
* The GAID, for an Android device.

### Showing a Rewarded Ad <a href="#id-01h8xqfjpzftc4n7pxvk48yax4" id="id-01h8xqfjpzftc4n7pxvk48yax4"></a>

There is no change to consider when showing a rewarded ad since the callback is always triggered upon video completion.

You must make sure that the User ID is set to the value you are interested in before showing your rewarded ad.

### Appending Custom Parameters <a href="#id-01h8xqfjpzwga1ynyzqpgg7r7y" id="id-01h8xqfjpzwga1ynyzqpgg7r7y"></a>

Use the code samples below to send extra parameters into your completion callback.

To do this, create an object with your custom parameters, which you pass using the show method.

{% hint style="info" %}
The total length of characters in the custom parameters collection must not exceed 4096. If it does, an empty collection of custom parameters is sent.
{% endhint %}

{% tabs %}
{% tab title="Android" %}
{% code title="Java" %}

```java
Map<String, String> customParameters = new HashMap<>();
customParameters.put("myCustomKey", "myCustomValue");
customParameters.put("anotherCustomKey", "anotherCustomValue");
RewardedOptions rewardedOptions = new RewardedOptions();
rewardedOptions.setCustomParameters(customParameters);
Rewarded.show("placementID", rewardedOptions, activity);
```

{% endcode %}
{% endtab %}

{% tab title="iOS" %}
{% code title="obj-C" overflow="wrap" %}

```objective-c
FYBShowOptions *showOptions = [FYBShowOptions new]; showOptions.customParameters = @{@"myCustomKey": @"myCustomValue", @"anotherCustomKey": @"anotherCustomValue"}; [FYBRewarded show:@"placementID" options:showOptions];
```

{% endcode %}

{% code title="Swift" overflow="wrap" %}

```swift
let showOptions = FYBShowOptions() showOptions.customParameters = ["myCustomKey": "myCustomValue", "anotherCustomKey": "anotherCustomValue"] FYBRewarded.show("placementID", options: showOptions)
```

{% endcode %}
{% endtab %}

{% tab title="Unity" %}
{% code title="Java" overflow="wrap" %}

```java
Dictionary<string, string> customParameters = new Dictionary<string, string>();
customParameters.Add("myCustomKey", "myCustomValue");
customParameters.Add("anotherCustomKey", "anotherCustomValue");
RewardedOptions rewardedOptions = new RewardedOptions();
rewardedOptions.CustomParameters = customParameters;
Rewarded.Show("placementID", rewardedOptions);
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Configuring Endpoints in the Console <a href="#id-01h8xqfjpz2dav8bhnacj5qv3b" id="id-01h8xqfjpz2dav8bhnacj5qv3b"></a>

1. Log in to the [DT Console](https://console.fyber.com/).
2. You can configure the endpoint in the Callback URL under **Configure Placement** in the console

<figure><img src="https://2654615282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4IftQ9WUOy9feTA5sZeE%2Fuploads%2FAHl0C5lrYlkSsn26BBWg%2Fimage.png?alt=media&#x26;token=275dfeb4-3c4b-48c0-9df1-300da257be3c" alt=""><figcaption></figcaption></figure>

3. Under Server Side Rewarding, click **Edit Server to Server Callback**. The Callback URL and Security Token are displayed

<div align="left" data-with-frame="true"><figure><img src="https://2654615282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4IftQ9WUOy9feTA5sZeE%2Fuploads%2FGXeGhL3tfv5ktjaxmAxT%2Fimage.png?alt=media&#x26;token=82b887b5-9453-4f99-8b06-d318fe3079f7" alt=""><figcaption></figcaption></figure></div>

4. Copy your security token. It is sent in each callback to enable you to validate that the response is coming from DT’s server
5. Click **Save**

{% hint style="warning" %}
Be aware of the following:

* The Security token should be kept secret between your servers and DT's. Ensure that there is no possible way that any of your users can access it.
* There is a significance to the order of the parameters in the Callback URL when computing the SHA1 hash of the request parameters.
  {% endhint %}

## Callback Structure and Behavior <a href="#id-01h8xqfjpz1aqpgfvvsk2v39zx" id="id-01h8xqfjpz1aqpgfvvsk2v39zx"></a>

DT calls your endpoint with the URL configured in the console.

Before performing the GET request with the URL, DT replaces the following macros with information related to the video completion event.

<table><thead><tr><th width="249">Parameter</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>USER_ID</td><td>Yes</td><td>The ID of the user to be credited</td></tr><tr><td>SIG</td><td>Yes</td><td><p>The value of the SIG macro.</p><p>For more information, see <a href="#the-sig-macro">The Sig Macro</a>.</p><p></p></td></tr><tr><td>AMOUNT</td><td>Yes</td><td>The amount of virtual currency the user is to be credited.</td></tr><tr><td>CURRENCY_NAME</td><td>No</td><td>The name of the virtual currency being rewarded as it appears in the console.</td></tr><tr><td>APP_ID</td><td>No</td><td>The Application ID as it appears in the console.</td></tr><tr><td>SESSION_ID</td><td>No</td><td>The unique transaction ID in the form of an <strong>int64</strong>. Use this to check whether the transaction has already been processed in your system.</td></tr><tr><td>TIMESTAMP</td><td>No</td><td>Indicates the time stamp when the completion event occurred.</td></tr></tbody></table>

### The SIG Macro

The value of the SIG macro is the SHA1 Hash of the values of all parameters (including the customized params even if they are not configured in the callback URL) in the URL (alphabetically sorted by parameter name) and the Security token displayed in the UI.

For example, if the callback URL is:

{% code overflow="wrap" %}

```html
https://mygamesdomain.com/callbacks.aspx?appID=123456&currencyName=Get%2Bcurrency&data=test123456test&reward_amount=1.000000&sessionID=1234567890123456789&signature=SIG&timestamp=1234567890123&user_id=test123456
```

{% endcode %}

('data' is the custom params in the project) and the security token in the UI is:

```
abcdefghijklmnopqrstuvwxyz123456789123zyxwvutsrqponmlkjihgfedcba
```

Then the string (URL Decoded) to be encrypted is:&#x20;

{% code overflow="wrap" %}

```
123456Get currencytest123456test1.00000012345678901234567891234567890123test123456abcdefgh
ijklmnopqrstuvwxyz123456789123zyxwvutsrqponmlkjihgfedcba
```

{% endcode %}

The SIG appears as:

```
10708d03944513ae9eeb95f958838cfeef66cf06
```

### Response Options <a href="#id-01h8xqfjq0p1jss7brp444zykk" id="id-01h8xqfjq0p1jss7brp444zykk"></a>

DT expects to receive a `HTTP 200` response to indicate that the publisher has successfully processed the callback. If a `HTTP 302` response is received, it is redirected a maximum of three times.

If the response is `HTTP 400` or `HTTP 401`, DT does not retry that attempt. For any other response, DT continues to resend the callback at increasing intervals until it receives a `HTTP 200` response or until the maximum 10 tries limit is reached.

DT's server decides whether the callback request was successful based on the HTTP status code of your response.

| Callback Request Type             | Description                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Response                          | A successful callback must return an empty response and a `HTTP 200` status code. This indicates to our servers that you have successfully processed the callback. Any other response is interpreted as an unsuccessful callback (see below).                                                                                                                                            |
| Redirects                         | DT’s servers follow HTTP redirects (status code 301 or 302), however, all redirect locations must be absolute URLs, as specified in the W3C standard.                                                                                                                                                                                                                                    |
| Unsuccessful Callbacks            | <p>If an error occurs on your side, you may send <strong>any status code other than <code>HTTP 200</code></strong> to indicate to our servers that the callback was not processed successfully.<br><br>Any response other than <code>HTTP 200</code> causes our system to resend the callback up to 10 additional times with an exponentially increasing delay between each attempt.</p> |
| Duplicates and Rejected Callbacks | If you identify the callback request as a duplicate based on the `SESSION_ID`, or if you choose to reject the callback intentionally, we recommend you to send an `HTTP 200` status code response. In this way, this indicates to us that the callback was processed and there is no need to resend it.                                                                                  |

{% hint style="warning" %}
To ensure the security of your reward callbacks, our servers send a `sig` (signature) parameter to authenticate the event. We highly recommend you verify this on your end.
{% endhint %}

### Whitelist DT IPs <a href="#id-01h8xqfjq03f45cazd69nzf1nq" id="id-01h8xqfjq03f45cazd69nzf1nq"></a>

If your server has restrictive security settings and/or is protected by a firewall, you may have to unblock DT’s servers’ IP addresses to receive callback requests.

Whitelist the following IP addresses:

{% hint style="info" %}
We have added a new list of IPs. They are due to come into effect over the next few months.
{% endhint %}

| New DT IP Address | Old DT IP Address |
| ----------------- | ----------------- |
| 34.139.213.214    | 52.203.142.28     |
| 34.23.52.214      | 54.82.252.137     |
| 34.23.119.91      | 52.21.200.98      |
| 35.243.128.240    |                   |
| 34.23.179.242     |                   |
| 104.196.223.181   |                   |
| 34.23.216.190     |                   |
| 35.196.84.62      |                   |
| 34.23.149.113     |                   |
| 34.73.158.22      |                   |