# Java Software Development Kit for Kevel Decision & UserDB APIs

- [Open Source on Github](https://github.com/adzerk/adzerk-decision-sdk-java)
- [Maven Package](https://central.sonatype.com/artifact/com.adzerk/adzerk-decision-sdk?smo=true)

## Installation

Requires [Java SE 8](https://en.wikipedia.org/wiki/Java_version_history) or higher.

Add to your `pom.xml` file:

```xml
<dependency>
    <groupId>com.adzerk</groupId>
    <artifactId>adzerk-decision-sdk</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>
```

Or `build.gradle` file:

```groovy
implementation 'com.adzerk:adzerk-decision-sdk:1.0.0-beta.1'
```

## Examples

### Fetching an Ad Decision

```java
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());
  }
}
```

### Recording Impression & Clicks

Use with the fetch ad example above.

```java
// 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());
```

### UserDB: Reading User Record

```java
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));
  }
}
```

### UserDB: Setting Custom Properties

```java
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);
  }
}
```

### UserDB: Forgetting User Record

```java
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");
  }
}
```

### Decision Explainer

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());
  }
}
```