Partner API

Reporting impressions & clicks

The recommended way of reporting impressions and clicks is directly to CitrusAd's /resource/ endpoint. Impressions are reported to the first-i resource, and clicks are reported to the second-c resource.

📘

Before you are able to report impressions and clicks, you will need to get your Base URL from your Technical Account Manager.

Calling endpoints should occur within the app or website.

With CitrusAd, the integration of a mobile app is almost identical to the integration of a website. As CitrusAd is integrated 'backend to backend', your ad requests will be identical to the requests you send on desktop and mobile. As apps do not support JS libraries, you will need to make a backend request to our click and impression endpoints.

Reporting impressions

To report an impression, you need to send a GET request in the format below:

https://$BASE_URL.citrusad.com/v1/resource/first-i/AD_ID

The AD_ID will be the adId returned to you with the ad you are reporting an impression for. An example GET request will look like the below:

https://$BASE_URL.citrusad.com/v1/resource/first-i/display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT

In the above, display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT is the adId you are reporting an impression for.

Reporting clicks

To report a click, you need to send a GET request in the format below:

https://$BASE_URL.citrusad.com/v1/resource/second-c/AD_ID

The AD_ID will be the adId returned to you with the ad you are reporting a click for. An example GET request will look like the below:

https://$BASE_URL.citrusad.com/v1/resource/second-c/display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT

In the above, display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT is the adId you are reporting a click for.

Javascript Library

The JavaScript Library (formerly the JavaScript SDK) makes it possible to send clicks and impressions reports to CitrusAd. The Javascript Library adds more tracking information, and can be used in web-based integrations.

❗️

Adblocked Resource

CitrusAd's JS Library is hosted at assets.citrusad.net. This resource is blocked by popular ad blocking software. The impact of this is that ads will be served, but impressions and clicks will not be reported, as the library is not fetched from CitrusAd.

It is advised that new integrators report orders via a GET request as outlined above, or consume the JS into their own native javascript.

The API currently exposes two methods, as outlined below:

<script type="text/javascript" src="https://assets.citrusad.net/citrusjs/1.2.0/citrus.js"></script>
<script type="text/javascript">
   var citrusAd = CitrusAd.init(
    'Get base URL from Citrus for your proper environment and region',
    {
      disableTracking: false, // Optional: defaults to false.
      trackingOptions: {
          sessionId: 'YOUR_OWN_TRACKING_TOKEN' // Optional, this token can be used to tie impressions/clicks with a session token that you maintain
      }
    }
  );
  citrusAd.reportClick('adId').then(function (result) {
    console.log(result);
  }).catch(function (error) {
    console.log(error);
  })
  citrusAd.reportImpression('adId').then(function (result) {
    console.log(result);
  }).catch(function (error) {
    console.log(error);
  })
</script>

Below is an example of how to include a file using a script tag:

<script type="text/javascript" src="https://assets.citrusad.net/citrusjs/1.2.0/citrus.js"></script>