Java Software Development Kit for Adzerk Decision & UserDB APIs
Requires Java SE 8 or higher.
Add to your pom.xml file:
<dependency>
<groupId>com.adzerk</groupId>
<artifactId>adzerk-decision-sdk</artifactId>
<version>1.0.0-beta.1</version>
</dependency>Or build.gradle file:
implementation 'com.adzerk:adzerk-decision-sdk:1.0.0-beta.1'Or, if using Clojure, add to your deps.edn file:
{:deps
{com.adzerk/adzerk-decision-sdk {:mvn/version "1.0.0-beta.1"}}}- Network ID: Log into Adzerk UI & use the "circle-i" help menu in upper right corner to find Network ID. Required for all SDK operations.
- Site ID: Go to Manage Sites page to find site IDs. Required when fetching an ad decision.
- Ad Type ID: Go to Ad Sizes page to find Ad Type IDs. Required when fetching an ad decision.
- API Key: Go to API Keys page find active API keys. Required when writing to UserDB.
- User Key: UserDB IDs are specified or generated for each user.
import java.util.*;
import com.adzerk.sdk.*;
import com.adzerk.sdk.generated.ApiException;
import com.adzerk.sdk.generated.model.*;
import com.adzerk.sdk.model.DecisionResponse;
public class FetchAds {
public static void main(String[] args) throws ApiException {
// Demo network, site, and ad type IDs; find your own via the Adzerk UI!
Client client = new Client(new ClientOptions(23).siteId(667480));
Placement placement = new Placement().adTypes(Arrays.asList(5));
User user = new User().key("abc");
DecisionRequest request = new DecisionRequest()
.placements(Arrays.asList(placement))
.keywords(Arrays.asList("keyword1", "keyword2"))
.user(user);
DecisionResponse response = client.decisions().get(request);
System.out.println(response.toString());
}
}Use with the fetch ad example above.
// Impression pixel; fire when user sees the ad
String impUrl = decision.getImpressionUrl().toString();
client.pixels().fire(new PixelFireOptions().url(impUrl));
// Click pixel; fire when user clicks on the ad
// status: HTTP status code
// location: click target URL
String clickUrl = decision.getClickUrl().toString();
PixelFireResponse clickResponse = client.pixels().fire(new PixelFireOptions() .url(clickUrl));
System.out.println("Fired! " +
"status: " + clickResponse.getStatusCode() + " " +
"location: " + clickResponse.getLocation());import com.adzerk.sdk.*;
import com.adzerk.sdk.generated.ApiException;
import com.adzerk.sdk.model.UserRecord;
import org.apache.commons.lang3.builder.ToStringBuilder;
public class FetchUserDb {
public static void main(String[] argv) throws ApiException {
// Demo network ID; find your own via the Adzerk UI!
Client client = new Client(new ClientOptions(23));
UserRecord record = client.userDb().read("abc");
System.out.println(ToStringBuilder.reflectionToString(record));
}
}import java.util.*;
import com.adzerk.sdk.*;
import com.adzerk.sdk.generated.ApiException;
public class SetUserDb {
public static void main(String[] argv) throws ApiException {
// Demo network ID; find your own via the Adzerk UI!
Client client = new Client(new ClientOptions(23));
Map props = Map.of(
"favoriteColor", "blue",
"favoriteNumber", 42,
"favoriteFoods", new String[] {"strawberries", "chocolate"});
client.userDb().setCustomProperties("abc", props);
}
}import com.adzerk.sdk.*;
import com.adzerk.sdk.generated.ApiException;
public class ForgetUserDb {
public static void main(String[] argv) throws ApiException {
// Demo network ID and API key; find your own via the Adzerk UI!
Client client = new Client(new ClientOptions(23).apiKey("YOUR-API-KEY"));
client.userDb().forget("abc");
}
}The Decision Explainer is a feature that returns information on a Decision API request explaining why each candidate ad was or was not chosen.
import java.util.*;
import com.adzerk.sdk.*;
import com.adzerk.sdk.generated.ApiException;
import com.adzerk.sdk.generated.model.*;
import com.adzerk.sdk.model.DecisionResponse;
public class FetchAds {
public static void main(String[] args) throws ApiException {
// Demo network, site, and ad type IDs; find your own via the Adzerk UI!
Client client = new Client(new ClientOptions(23).siteId(667480));
Placement placement = new Placement().adTypes(Arrays.asList(5));
User user = new User().key("abc");
DecisionRequest request = new DecisionRequest()
.placements(Arrays.asList(placement))
.keywords(Arrays.asList("keyword1", "keyword2"))
.user(user);
AdditionalOptions options = new AdditionalOptions()
.includeExplanation(true)
.apiKey("API_KEY");
DecisionResponse response = client.decisions().get(request, options);
System.out.println(response.toString());
}
}The response returns a decision object with placement, buckets, rtb logs, and result information.
{
"div0": {
"placement": {},
"buckets": [],
"rtb_log": [],
"results": []
}
}The "placement" object represents a decision in which an ad may be served. A Explainer Request can have multiple placements in the request. The "buckets" array contains channel and priority information. The "rtb_logs" array contains information about Real Time Bidding. The "results" array contains the list of candidate ads that did and did not serve, along with a brief explanation.
(ns readme-ad-request
(:import (com.adzerk.sdk Client ClientOptions)
(com.adzerk.sdk.generated.model DecisionRequest Placement User)))
(defn -main []
; Demo network, site, and ad type IDs; find your own via the Adzerk UI!
(let [client (Client. (doto (ClientOptions. (int 23)) (.siteId (int 667480))))
request (doto (DecisionRequest.)
(.placements [(doto (Placement.) (.adTypes [5]))])
(.keywords ["keyword1" "keyword2"])
(.user (doto (User.) (.key "abc"))))]
(print (-> client (.decisions) (.get request)))))Use with the fetch ad example above.
; Impression pixel; fire when user sees the ad
(-> client (.pixels) (.fire (doto (PixelFireOptions.) (.url (.toString (.getImpressionUrl decision))))))
; Click pixel; fire when user clicks on the ad
; status: HTTP status code
; location: click target URL
(let [decision-url (.toString (.getClickUrl decision))
pixel-results (-> client (.pixels) (.fire (doto (PixelFireOptions.) (.url decision-url))))]
(println (str "Fired! status: " (.getStatusCode pixel-results)
"; location: " (.getLocation pixel-results))))))(ns readme-read-userdb
(:use clojure.pprint)
(:import (com.adzerk.sdk Client ClientOptions)))
(defn -main []
; Demo network ID; find your own via the Adzerk UI!
(let [client (Client. (doto (ClientOptions. (int 23))))]
(pprint (bean (-> client (.userDb) (.read "abc"))))))(ns readme-set-userdb
(:import (com.adzerk.sdk Client ClientOptions)))
(defn -main []
; Demo network ID; find your own via the Adzerk UI!
(let [client (Client. (doto (ClientOptions. (int 23))))
props {"favoriteColor" "blue"
"favoriteNumber" 42
"favoriteFoods" ["strawberries", "chocolate"]}]
(-> client (.userDb) (.setCustomProperties "abc" props))))(ns readme-forget-userdb
(:import (com.adzerk.sdk Client ClientOptions)))
(defn -main []
; Demo network ID and API key; find your own via the Adzerk UI!
(let [client (Client. (doto (ClientOptions. (int 23)) (.apiKey "YOUR-API-KEY")))]
(-> client (.userDb) (.forget "abc"))))- For bug fixes and improvements to this SDK please use Github to open an issue or send us a pull request.
- For questions or issues regarding Adzerk functionality, please contact Adzerk support.
./gradlew build