On-Prem HTTP Server

Getting Started

This document describes the implementation of the Server version of Geopulse On-Prem. See the Geopulse On-Prem Overview for a higher-level introduction to Geopulse On-Prem. Before provisioning servers, see the Hardware Guidance in the Geopulse On-Prem Overview.

Required Software

The Geopulse On-Prem HTTP Server is developed and tested against the following system environment:

  • Oracle JDK 7
  • Ubuntu 14.04

The following packages are also required:

  • upstart (installed by default on Ubuntu)
  • cronolog

Use only the Oracle JDK — issues with the SSL implementation of OpenJDK have been encountered in production deployments which can prevent Geopulse On-Prem from updating its audience and geofence data.

Installation

Create a new user

First create a factual user:

$ createuser factual

Download On-Prem Server

Next, download the latest On-Prem Server binary from the On-Prem Downloads page. Unpack and copy the provided files to /usr/local/factual/outpost.

$ mkdir -p /usr/local/factual/outpost
$ cd /usr/local/factual/outpost
$ wget [download link]
$ tar -xvzf outpost-3.1.4-example.tar.gz
$ cp -a outpost-3.1.4-example/. /usr/local/factual/outpost/

You’ll also want to create the following directory for storing logs:

$ mkdir -p /var/log/factual/outpost

Copy the outpost.conf file provided in the top-level into /etc/init.

$ cp /usr/local/factual/outpost/outpost.conf /etc/init/outpost.conf

Edit your config file

Edit the config.yml file, and add in your Organization ID under the comment “the organization-id for the user”. Your account manager can provide this value upon request.

# the organization-id for the user
b3bda92e-b4b5-4012-bccc-48017cdefc81:
  # the credentials for the organization, available via http://factual.com
  api-key: ""
  secret-key: ""

Next configure the values for source that you will pass in to On-Prem. source is the data source/exchange on which the impression originated. Your config.yml file supports aliasing of data sources. This means that you can map the name of the exchange you pass to On-Prem, to the name that Factual uses to refer to that exchange.

The following table provides a mapping of these values:

Data Source/Exchange Factual Source Value
MoPub mopub
AOL One nexage
Smaato smaato
Aerserv aerserv
OpenX openx
Factual factual_dap

Per the snippet below, setup your config.yml with your desired data source mappings.

global:
  directory: /tmp/on-prem/test-org
test:
  audience:
    sets:
      max-memory: 1
      fields: [designId, targetingCode, dataSource]
      deployment-tags: []
      data-source-aliases:
        aerserv: internalAerservName
        mopub: internalMoPubName
        nexage: internalAOLName
        smaato: internalSmaatoName

Using Upstart

We strongly recommend using Upstart. Under normal operation, On-Prem Server should never crash. However, if it should, you can take the simple precaution of using Upstart to help maintain availability in production.

You’ll need to confirm that your server can open a large number of file descriptors, which can be done with the following command:

$ limit nofile 500000 500000

Running the Server

Startup the On-Prem server by running the following command:

$ sudo start outpost

Once the server is running, the following message should appear in /var/log/factual/outpost/outpost.log:

started HTTP server on 8989

If desired, the port can be changed in the outpost.conf file. You can confirm that the server is running by hitting the /zz/health endpoint.

$ curl http://localhost:8989/zz/health

ok

The server can be stopped and restarted with the following commands:

$ sudo stop outpost
$ sudo restart outpost

Testing Responses

Use curl for testing your installation. Remember to wrap the URL in quotes:

Audience test:

$ curl "http://[server]/geopulse/audience?user-id=<device_id>&source=<data_source>"

Proximity test:

$ curl "http://[server]/geopulse/proximity/indices?latitude=40.642875&longitude=-73.782991"

Match Response

Although Geopulse Proximity and Geopulse Audience are two different products, with their own specific use cases, Geopulse On-Prem powers each, or both concurrently. To facilitate integration and onboarding, we’ve designed the response packets to be identical:

Attribute JSON Field Description
Design Name designName Name of the Geopulse Proximity or Audience Design, assigned in the Designer UI.
Design ID designId Factual generated unique ID for the Design.
Deployment ID deploymentId Factual generated unique ID for the associated deploy of the Design.
Deployment Tags deploymentTags String tags associated with the deploy of the Design as assigned.
Targeting Code targetingCode A string assigned to the Set when designing the Design in the Designer UI. (In deprecated versions this was formerly called the “Group ID”.)
Data Source dataSource Factual provided ID for the associated audience data source. (Geopulse Audience only)
Metadata metadata A map of keys and values describing the matched set within the Design.
Payload payload JSON payload describing the matched set, available as string or bytes (Proximity only)

See the page on Geopulse Terminology for detailed descriptions of each return value.


Proximity Response Example

[
  {
    "designName": "BigBox",
    "targetingCode": "Costco",
    "deploymentId": "ABCEHGEEG3q45hasdShe",
    "setId": "xyzHGEEG3q45hasdShe"
  }, 
  {
    "designName": "Electronics",
    "targetingCode": "Best Buy",
    "deploymentId": "ABMnOwHGbdcG3q45haoazq",
    "setId": "xyzHGEqa68Dxhasdhe"
  }
]


Audience Response Example

[
  {
    "designName": "affluent-business-travelers",
    "designId": "17914b5c-899b-434a-b343-cbadec91e7ca",
    "targetingCode": "affluentBiz",
    "deploymentId": "AyoLwbEHGbdcG3q45haoae",
    "setId": "xyzHlQbiqa353q45ha3h9e"
  }, 
  {
    "designName": "san-diego-moms",
    "designId": "9653e9dd-236d-4c53-8398-ca73a3876343",
    "targetingCode":"SanDiegoMoms",
    "deploymentId": "ABCEHGbdcGwZqb3q45hao9e8",
    "setId": "xyzHqGExqsa353q45hys5he7"
  }
]