Skip to content
Service to deliver sponsored content while preserving privacy
Python Shell Dockerfile
Branch: master
Clone or download
mmiermans Fixed campaign cap and updated domain affinities (#5)
* Updated domain affinities to current lists

* Increased lifetime cap to 50

The lifetime cap is applied to campaigns, which are long lived.
Increasing this will give us some more time to have a change ride
the Firefox train that will apply this value on the flight level.

* Add flight cap and flight_id

This copies over work from PR#4.

* Fixed spoc transform test
Latest commit 3bb44c7 Nov 6, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
pip.lock Initial commit Oct 24, 2019

Spocs Proxy Server

This service sits between Firefox and AdZerk. Its purpose is to preserve the privacy of Firefox clients when they request sponsored content (spocs) for the Firefox New Tab. See Sponsored Stories FAQ for more information.


See OpenAPI documentation.

Development environment

The following steps create a Docker development environment to run this service locally.

  1. Install Docker and Docker Compose.
  2. In the project root run: docker-compose build.
  3. Start a mock s3 service: docker-compose up s3.
  4. Copy MaxMind GeoIP2 to pocket-geoip/GeoIP2-City.mmdb on the mock s3 container.
    1. If the database is stored on s3:
      images/s3/ -p <aws profile> -b <s3 bucket>
    2. If it's stored on disk in a file called GeoLite2-City.mmdb:
      aws --endpoint-url http://localhost:4569 s3 cp GeoLite2-City.mmdb s3://pocket-geoip/GeoIP2-City.mmdb
  5. Verify that GeoIP2 is available at localhost:4569/pocket-geoip/GeoIP2-City.mmdb.
  6. Start the application containers: docker-compose up.
  7. Test that the application is running: http://localhost/pulse. It should return {"pulse":"ok"}.


See the Test README.


The first time the service is deployed, follow the steps in the CloudFormation README.

Deploy EMR images

Run ./ with the following arguments:

  • -p AWS profile name from ~/.aws/config
  • -a ECR URI for the app container
  • -n ECR URI for the nginx container

For example:

./ -p pocket-proxy-rw \
-a "" \
-n ""

Deploy Fargate

Open Fargate in the AWS console and update the service, forcing a new deployment.

Telemetry Function

The Telemtry Handler is triggered by telemetry from the Firefox discovery stream. It anonymously pings AdZerk to keep track of events related to sponsored content, such as clicks and impressions in a privacy-preserving way. The event code (or "shim") does not contain any personally identifiable data; we never share personal data with AdZerk.


  1. Open telemetry-proxy in the Google Cloud Console
  2. Click Edit and paste the new code
  3. Click Deploy
You can’t perform that action at this time.