Skip to main content

Calling the Impression Server

In order to call an impression server using the Java API, to need to first establish a session.

Let's start with this FDL file:

namespace "io.causallab.example"

session {
args {
visitorId : ID! @persistent_key
arrivalId : ID! @session_key

The above block defines an FDL session with two arguments that can be used to identify a particular Causal session.

Creating a Session

The Java code to establish a session is in the SessionRequest class. So, since our namespace is io.causallabs.example, the full name of the class is io.causallabs.example.SessionRequest.

In order to create a session, call the main class constructor with the session arguments:

SessionRequest session = SessionRequest.builder()
.visitorId( "Visitors ID" )
.arrivalId( "Arrival ID" )

You may reuse the session object as much as you'd like, there's no need to create a separate instance for subsequent requests.

Making a Request

Let's extend our FDL file with a new feature definition and then request an impression. We can add this to the example FDL file and generate the code.

feature Simple
args {
simpleInput : Int!
output {
simpleOutput : Int! = 42

With that definition, we can generate a request for the simple feature by making a request object, passing in the required arguments:

SimpleRequest req = new SimpleRequest.builder().simpleInput(123).build();

You can optionally initialize the CausalClient by calling the init static method. Currently it just takes the url of the impression server you'd like to connect to.


If you do not call init, the impression server url will come from the CAUSAL_ISERVER environment variable, and failing that, the io.causallabs.iserverUrl system property.

Finally, make the request using one of the CausalClient's request methods. CausalClient has request methods for synchronous and asynchronous operations. Each can take multiple requests per call.

CausalClient.getInstance().request(s, req);

The request methods can also take an impression id. If you have your own notion of an impression ID, we encourage you to pass those in with the request.

The request may throw an exception if it has trouble communicating with the impression server. However, because Causal has a robust calling convention, you will typically be able to ignore the error and continue executing with the data stored on the request objects. If Causal encounters an error because of a schema mismatch between the client and the impression server (as opposed to a communication error), an error will not be thrown. This is considered a normal part of schema migration.

Once the request is complete, you'll be able to access the plugin and output values on the session and request objects.

You can access the feature's output using the accessor methods on the request object:


Signalling an Event

Next, let's add an event to our feature:

feature Simple
event Click {
clickValue : Int!

Signal a click using the SimpleReqest.signalClick method, which takes the event's fields as arguments:

// pass in clickValue

Events defined in the session block also create a corresponding method on the SessionRequest object.

Keep Alives

Some areas of your application may not use Causal yet. However, you may still like to inform Causal that the user is active on the site. For example, to prevent sessions from expiring too early, or to accurately calculate the session end time.

You can call the CausalClient.keepAlive method to inform the impression server that the user is still active. This is a very lightweight, asynchronous call. There should be no latency introduced in your application, and the load on the impression server will be light.