gdk-scala

What this is

The Gravity Development Kit (GDK) is a suite of SDKs that assist developers integrating with Gravity.

What this isn't

This SDK does not help you harness the force that attracts bodies of mass to one another.

TOC

Usage

Installation

This library is published for Scala 2.10.6 and 2.11.8.

For SBT

// JavaX servlet is required by GDK but not provided so you can use your own version
libraryDependencies += "javax.servlet" % "servlet-api" % "2.5"

// GDK
libraryDependencies += "com.gravity" %% "gdk-scala" % "0.0.3"

For Maven

You should replace _2.11 in the artifactId with _2.10 or _2.11.

<!-- JavaX servlet is required by GDK but not provided so you can use your own version -->
<dependency>
  <groupId>javax.servlet</groupId>
  <artifactId>servlet-api</artifactId>
  <version>2.5</version>
</dependency>

<!-- GDK -->
<dependency>
  <groupId>com.gravity</groupId>
  <artifactId>gdk-scala_2.11</artifactId>
  <version>0.0.3</version>
</dependency>

Imports

You can get most things you will need from this one import:

import com.gravity.gdk.Common._

Get article recommendations

import com.gravity.gdk.Common._
import scala.concurrent._
import scala.concurrent.duration._

// Your account manager at Gravity will provide you with a placement ID (typically 4 or 5 digit number)
val pk = new PlacementKey(1234L)
val p = new Placement(pk)

// This, or use your own execution context
import scala.concurrent.ExecutionContext.Implicits.global

// You can build your own recoCtx, or if you are getting recos within a Java servlet request representing a request 
// to your server by the user for whom you are getting recos, you can do this:
implicit val recoCtx = RecoContext.fromRequest

// This is a future resolved with the RecoResult
val recoResultF = p.getRecos()

val recoResult = Await.result(recoResultF, Duration.Inf)

for(article <- recoResult.articles)
  println(article.title)

Building a RecoContext

user: GravityUser

Ordinarily, Gravity tracks users across disparate domains via a unified user GUID for the given user propagated in cookies: one cookie on the gravity.com domain that facilitates the crossdomain unification, and one cookie on the partner domain. Essentially, a user is typically identified by a 32-char hex user GUID.

In certain scenarios, you can correlate your own site's user IDs with Gravity user GUIDs; talk to your account manager if you wish to pursue this.

A GravityUser can be inferred from a Java servlet request, or a set of Java cookies automatically; see GravityUser.fromRequest and GravityUser.fromCookies.

currentUrl: String

Some Gravity recommendation algorithms use the contents of the user's currently viewed page URL as a vector for recommendations (so-called "contextual recommendations"). So the user's current article URL should be passed for this parameter, if possible, or if a fallback is needed (such as for offline-generated recos) you can use a generally contextually relevant URL, such as your site's home page or a page containing textual descriptions of your site's content (e.g. "About Us").

imageWidth: Int and imageHeight: Int

Passing either or both of these params influences the image URLs returned in the RecoResult.articles to facilitate simple thumbnail generation using highly available, highly performant thumbnail services offered by AOL.

pageViewGuid: PageViewGuid

The page view GUID is intended to be a unique identifier (usually generated with PageViewGuid.random) with which to identify a given incarnation of a Web page view on which a placement appears. An obvious use case is for pages with multiple distinct placements; in this case, the page view GUID for those multiple placements should be the same for a given page view, and then article recommendations may be deduped across placements for the given page view.

Inferring a RecoContext from a Java servlet request

If you are obtaining recommendations from Gravity during a live user request to your site, you may leverage the Java servlet request to infer a RecoContext. Notably, the inferred GravityUser is obtained from the Gravity cookie that would normally be present on your domain (see notes on GravityUser). Note that you must have the Gravity beacon installed for this wiring to exist; ask your account manager about the beacon if you aren't sure of what that is.

Placement.getRecos params of note

logImpression

The simplest use case for generating recos (and impressions) is to have the impression logged automatically upon generating recos. The assumption in this case is that all the recommended articles will be shown to the user (and in the recommended order). So it follows then that if you intend to modify the recommendations after having received them (e.g. reordering, removing certain articles, trimming off the last few) Gravity should not log the default impression and instead an impression that represents your modifications.

In the given example above, you will want to set logImpression to false and subsequently log an impression using Impression.log—and that point you will be able to specify the articles that were shown to the user, among other things. For more information see Async impression logging.

Async impression logging

For information on why you would do this, please see Placement.getRecos params of note: logImpression.

You will use the RecoResult future as described in Get article recommendations in order to log an impression:

import com.gravity.gdk.Common._
import scala.concurrent._
import scala.concurrent.duration._

// ...

val recoResultF = p.getRecos()

val impF = Impression.log(pk, recoResultF, /* optional customized article set to log in the impression */)
Await.ready(impF, Duration.Inf)

Release checklist

  1. Update versions in the version.sbt file (if needed; the minor part is automatically bumped during sbt version so if that suffices for the release, then you're fine), and in this README.md.
  2. Update the Changelog below.
  3. sbt publish
  4. Release in Sonatype.

Changelog

0.0.3

  • Implementation against Athena-compliant API.

0.0.2

  • RecoResult.meta needs to be optional.

0.0.1

  • Initial release.