CloudServices/Roadmaps/Campaign-Manager

From MozillaWiki
Jump to: navigation, search

Overview

Description

The Campaign-Manager 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 campaign 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.png

Campaign-Manager Service

Overview

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

Note, this product was originally called "snippets", and was renamed to avoid confusion. There are some residual uses of the term "snippet".

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 campaign DB, and API access to the metrics server

Client API

/announce

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

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

The 1 in the path is a version identifier for this protocol. The current version, as described in this document, is 1.

product is a broad identifier for the product being targeted. The current allowed value is simply android, but one can imagine desktop, firefoxos, or metro as additions.

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 campaign.

204 No Content Request was successful, no available campaigns, 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 campaigns 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/1/<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.

Campaign Format

{"announcements": [{
   "id": "12345678",                                               // a numeric ID, tracked by the client to ensure we don't display campaigns 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 /announce/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
{"announcements":[{
   "id": "12345678",
   "url": "https://campaigns.mozilla.org/redirect/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/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 )

Hardware Requirements

Speculative Requirements

The following are a speculative list of machines required. Operations has NOT signed off or agreed to this list. Please refer to Operations for the definitive list of required hardware.

  • Campaign Database
    • A pair of relational database machines.

Due to the heavy index use, recommend a master/client so that master writes do not impact client reads.

  • Campaign request serving web heads

(TODO: Need to run perf. tests to see RpS of system) TODO: Need expected RpS for initial launch + expected growth)

  • Redirect server
    • tied to read only Campaign database. Pulls url request, records hit to metlog system, redirects to proper URL.
    • May be the same machine as the request serving web head
  • Admin web head

Protected campaign management machine. (Single machine should suffice)

All data logging is being done via Metlog and should require no additional hardware.

Issues and Concerns

  • TODO: which redirect code will avoid duplicate hits and not screw up caches?
    • Currently using a reasonably meaningless ID based on campaign creation time + random value. (e.g. "1tjzaJ112")
    • rnewman: I meant "which HTTP redirect response code".
  • TODO: do we have a query param on the redirector to allow tracking? Talking with JR I think we do
    • Not so sure about that. The tracking param would be integrated into the click URL (e.g. the many redirectors out there that then boot to a proper URL)
    • Put it this way: when Firefox hits the redirector URL, it will not be including the platform/version/channel etc. information that you need to compute clickthrough rates. You need to add a parameter to the redirector URL returned in each snippet, which could feasibly be the chunk of URI that arrived with the request.

Operations

Hardware Request and Status

The project is expected to require:

  • A central db (SQL based)
  • Memcached (optional)
  • web heads:
    • campaign data delivery (to devices)
    • redirect servers (to handle tracking links from users)
  • Connection to the Services Metrics system.

System Demands

Remote clients request Announcements that match a given set of criteria. The servers provide a set of announcements that the client places on pages for user action. When a user selects a link associated with the announcement, the user is directed to a tracking URL that records the user action and delivers the original destination URL.

No individual user information is recorded. Privacy has already been briefed.


Current undetermined elements

I do not have full information for the following:

1. Expected QpS or Customer load.

The target audience currently is "Android", with "B2G" expected shortly after. Devices would poll for updates at first launch, then again at an undetermined period beyond that (~24+ hr). A connect failure is non-critical, but the device will retry afterwards. Redirect links will record data associated with the campaign to metrics and return a 302 for the correct, associated link.

2. Number of active campaigns.

The number discussed currently is "20". I expect that, the number will probably be closer to "100". Data records are not expected to be over 1K each and should fit within memory

Security Review

Review the Server side components of Campaign Manager

Introduce Feature (5-10 minutes) [can be answered ahead of time to save meeting time]

This feature provides the server components to remote clients for the Campaign Manager. It accepts general device profile information including:

  • Product (e.g. "android")
  • Channel (e.g. "nightly")
  • Platform (e.g. "ARMv6")
  • Version (e.g. "18.0")
  • User Locale and Language (e.g. "en-US")
  • Idle time in days

and returns a set of candidate messages to display to the user. Messages include a title, brief call to action message and an action URL.

The URL passes through the redirector function which records that the url for the campaign has been selected. No other user specific information is recorded.

Goal of Feature, what is trying to be achieved (problem solved, use cases, etc)

See above.

tl;dr: Campaigns attempt to re-engage users who may not be using the device as frequently as we'd prefer.

What solutions/approaches were considered other than the proposed solution?

Since this is a mozilla specific concern and issue, with tight integration to the client, I don't believe that other solutions were considered.

Why was this solution chosen?

Any security threats already considered in the design and why?

The biggest thread is the authoring system. We rely on persona providing a fully verified email address, then check that the provided address originates with @mozilla.com or @mozilla.org. Rogue entries could be blocked by a 'whitelist', however entries are recorded with the author's email and could be easily identified.


Threat Brainstorming (30-40 minutes)

Conclusions / Action Items (10-20 minutes)

Bugs & Related links

New Bugs:

Retrieved from "https://wiki.mozilla.org/index.php?title=CloudServices/Roadmaps/Campaign-Manager&oldid=765719"