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

Java

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" )
                     .build();

Ruby

The Ruby code to establish a session is in the Session class.

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

session = SessionRequest.new(visitor_id: "Visitors ID", arrival_id: "Arrival ID" );

Snake Case

Note that Causal follows the Ruby convention that methods and attribute names are in snake-case. The session argument names are converted to snake-case for the Ruby API.

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:

Java

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

Ruby

req = SimpleRequest.new(simple_input: 123);

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.

Java

CausalClient.init("http://my-iserver-url");

Ruby

CausalClient.init(url:"http://my-iserver-url");

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.

Java

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);

Ruby

Finally, make the request using the Session's request method. You may pass several request objects in for a single call to Session.request.

session.request 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:

Java

req.getSimpleOutput();

Ruby

req.simple_output

Signalling an Event

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

feature Simple
{
    ...
    event Click {
        clickValue : Int!
    }
}

Java

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

// pass in clickValue
req.signalClick(10);

Ruby

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

// pass in clickValue
req.signal_click(click_value: 10);

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.