Overview

Description

The snippets service exists to enable targeted messaging towards end users of Firefox for Android, based on platform, version, and time since last use. The initial use cases centre around recapturing users who have stopped using Firefox on Android by communicating about product improvements and new features.

High Level Architecture

As a concept, there are four logical components to delivering this service:

• The public snippet service, which delivers messages and tracks conversions.
• The snippets database, which contains all of the campaign data (text and URLs for all locales)
• The metrics server, which contains and collates all of the collected data (effectively impressions and click-through data)
• The campaign management tool, which allows individuals to create and manage individual campaigns.

Snippet Service

Overview

The snippet service handles two tasks: responding to snippet requests, and redirecting clients to the end URL, and tracks the results of both actions.

Privacy and Security Considerations

• Metrics tracking will be generally by coarse buckets, only tracking impressions and clicks using the API-provided information.
  • Platform ("ARM v6")
  • Channel ("Beta")
  • Version ("17.0b1")
  • Locale ("en_GB")
  • Idle Time (in days)
• There is no business need to track users longitudinally via this service.
• Cookies will not be used or set by this service.
• The public-facing service will only have read access to the snippets DB, and API access to the metrics server

Client API

/snippets

GET /snippets/<channel>/<version>/<platform>
Accept-Language: <comma-separated list of acceptable languages>

On a successful request, when there is an available snippet, this will return a JSON array of objects containing all needed information required to display a user notification.

channel is one of firefox, beta, aurora, nightly, or dev.

version is a version string such as 17.0a2.

platform is a platform identifier corresponding to the build variable ANDROID_CPU_ARCH. Currently this is one of armeabi-v7a, armeabi, mips, x86.

If the client is aware of the number of days since the browser was last launched, an idle query parameter can be appended to the URL. If the browser hasn't been launched, or the duration is unknown, this parameter should be omitted.

Headers

If-Modified-Since Standard HTTP header, passes the time of the last successful request by the client.

HTTP Responses

200 OK Returns JSON in the body with the information required for the service to display a notification. Content-Location header to a fixed path to the snippet.

204 No Content Request was successful, no available snippets, no data to return.

304 Not Modified No changes since the previous request. Only returned if If-Modified-Since is present in the request. The service will only return snippets newer than the given time.

400 Bad Request The request itself or the data supplied along with the request is invalid. The response contains a Cornice error payload indicating the reason for why the request was rejected.

405 Method Not Allowed The request URL does not support the specific request method. For this API it's "anything except GET".

503 Service Unavailable Indicates that the server is undergoing maintenance. Such a response will include a Retry-After header, and the client should not attempt another API call for the number of seconds specified in the header value. The response body may contain a JSON string describing the server’s status or error.

/redirect

GET /redirect/<locale>/<campaign>

Headers

None

HTTP Responses

302 Found

Returns a standard HTTP redirect to the appropriate campaign URL

If the campaign is over, or the provided information is not present, we will redirect to mozilla.org.

503 Service Unavailable Indicates the service is undergoing maintenance.

Snippet Format

{"snippets": [{
   "id": "12345678",                                               // a numeric ID, tracked by the client to ensure we don't display snippets multiple times
   "url": "https://campaigns.mozilla.org/en_US/9j2q98fdqjdaff3ar", // redirector URL, in order to track click-throughs
   "title": "Get awesome stuff",                                   // The main text for the notification
   "text": "It's awesome"                                          // the added string to display
}]}

Sample call

GET /snippets/firefox/AndroidARMv7/18?idle=5
Accept-Language: en_US

Note: we'll construct the Accept-Language header using the Firefox UI and/or system locales. As many locales in Firefox include "en-US, en" in this header, using the raw header Firefox would use is probably not ideal, as we don't want to provide notifications in a locale the user isn't actually capable of reading.

HTTP 200
{"snippets":[{
   "id": "12345678",
   "url": "https://snippets.mozilla.org/redirect/en_US/9j2q98fdqjdaff3ar",
   "title": "Get awesome stuff",
   "text": "It's awesome"
}]}

At this point the client will display an Android notification, which on click will open the URL in Firefox.

GET /redirect/en_US/9j2q98fdqjdaff3ar

Which should respond with:

HTTP/1.1 302 Found
Location: http://mozilla.org/get-your-awesome-on

Note: Firefox will handle this automatically, displaying the chosen URL (i.e. http://mozilla.org/get-your-awesome-on )

TODO: which redirect code will avoid duplicate hits and not screw up caches? TODO: do we have a query param on the redirector to allow tracking? Talking with JR I think we do…