What this is
The Gravity Development Kit (GDK) is a suite of SDKs that assist developers integrating with Gravity.
- GDK Scala (for S2S integration) ← YOU ARE HERE
What this isn't
This SDK does not help you harness the force that attracts bodies of mass to one another.
- Get article recommendations
- Building a RecoContext
- Placement.getRecos params of note
- Async impression logging
- Release checklist
This library is published for Scala 2.10.6 and 2.11.8.
// 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"
You should replace
_2.11 in the
<!-- 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>
You can get most things you will need from this one import:
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
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.
GravityUser can be inferred from a Java servlet request, or a set of Java cookies automatically; see
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
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.
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
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
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)
- Update versions in the
version.sbtfile (if needed; the minor part is automatically bumped during
sbt versionso if that suffices for the release, then you're fine), and in this
- Update the Changelog below.
- Release in Sonatype.
- Implementation against Athena-compliant API.
RecoResult.metaneeds to be optional.
- Initial release.