Firefox Affiliates¶

What is Firefox Affiliates?¶

Firefox Affiliates is a website that allows users to generate links that can be embedded on a website. Affiliates then measures the number of people clicking on these links and logs that data for the user who generated the link.

Administrators of Firefox Affiliates create things called banners, which serve as templates that users generate links from. There are several types of banners:

• Image banners, which show an image link when embedded.
• Text banners, which show a text link when embedded.
• Update banners, which show an image link when embedded. The image shown changes if the user has an up-to-date version of Firefox installed or not.

Banners are organized under categories and subcategories. When you go through the link generation flow, the first step is to choose a category. Within each category is a set of banners to choose from. Once you’ve chosen a banner, you must choose which variation of the banner to use. Variations are all related to the same subject (and thus are part of the same banner), but vary in size, color, and language.

What data does Firefox Affiliates store?¶

For each link that a user generates, Affiliates stores the number of times someone has followed the link, called link clicks. The number of link clicks per day is stored for the past 90 days from the present. After 90 days, the link click count is aggregated into a single count of the total link clicks for the link since it was created.

In practice, what this means is that per-day link click counts for any link are only available for the past 90 days. If you wanted the total link clicks for a date more than 90 days in the past, you’re out of luck!

The total number link clicks since a link was created is always available, of course.

Accessing the Banner Admin¶

The steps below describe how to access the admin interface for banners:

1. Open https://affiliates.mozilla.org/admin/ in your browser.
2. If a popup saying “Authentication Required” and “Mozilla Corporation - LDAP Required” appears, enter in your Mozilla LDAP credentials and click OK.
3. You will be shown a login form asking for a username and password. These Affiliates-specific credentials should have been provided to you by an existing admin or developer. Enter the username and password you were given and click “Log in”.
4. Once logged in, you will see the Admin dashboard. There are several boxes with lists of admin panels you can access; the banner admin panels are in the box titled “Banners”.

Adding Image Banners to Affiliates¶

If you want to add a brand new banner to Affiliates, you’ll need to gather the following:

• A name for the banner, and names for any new categories or subcategories that need to be created. Since these need to be localized, they need to be chosen early and submitted for localization by a developer.
• The URL for the Banner to redirect to.
• The actual images to use for the banner. At least one of these must be 125x125 pixels, otherwise an empty preview will be shown for the banner on the site.

Once you’ve gathered all these and had the necessary strings translated, you can upload the banners to the site via the admin interface:

1. Access the Banner Admin using the directions above.
2. Enter the Image Banner Admin by clicking the “Image banners” link. Then click the button to “Add image banner”.
3. Enter the name of the banner, and select the category it belongs under. Note that you must select a subcategory. The select box shows two levels of categories, with subcategories being indented underneath their parent category.
4. Enter the URL you wish users to be sent to when they click the banner under the “Destination” field.
5. Make sure the “Visible” checkbox is checked. If it is unchecked, the banner will not show up in the generator on the site.
6. Under the “Image banner variations” section, click the “Add another Image Banner Variation” link to add fields for a variation. Select the color and locale of the image you’re adding, and use the file field to select the image file for that variation.
7. Once you have added all the variations for the banner, click the save button to submit your changes and save the banner to the database.

Once you’ve saved the banner, you should log in to the website to check if the new banner is available, localized, and that you can create links using it correctly.

Updating Existing Image Banners¶

Sometimes, we need to update the image being used in an Image Banner. It is vital to note: any new images must be the same size as the image they are replacing [1].

It is highly recommended that, prior to replacing the images, you create some banners using the images you intend to replace, and copy the embed codes for them to a test page, like jsfiddle. That way, once you’re done, you can go back and check to see if the replacement worked.

Once you have the new images, you can update the old images via the image banner admin:

1. Access the Banner Admin using the directions above.
2. Enter the Image Banner Admin by clicking the “Image banners” link. Locate the banner with the images you need to replace and click it’s name to open the banner editing page.
3. Search through the list of “Image banner variations” at the bottom of the page to find the variations that need to be replaced. You can Ctrl-Click or Cmd-Click the image filenames shown in the “Image” column to open the images in a new tab and ensure they’re the right ones to replace.
4. Use the file input in the “Image” column to select the replacement image for each variation that needs to be replaced.
5. Once all the replacements have been selected, click the save button to save your changes.

After saving, you should check the website to see that the images have been updated, as well as checking the old banners you created beforehand to ensure they’ve been replaced as well.

Installation¶

These instructions assume you have git and pip installed. If you don’t have pip installed, you can install it with easy_install pip.

1. Start by getting the source:

   $ git clone --recursive git://github.com/mozilla/affiliates.git
   $ cd affiliates

2. Create a virtual environment for the libraries. Skip the first step if you already have virtualenv installed:

   $ pip install virtualenv
   $ virtualenv venv
   $ source venv/bin/activate
   $ pip install -r requirements/compiled.txt

3. Set up a local MySQL database. The MySQL Installation Documentation explains this fairly well.

4. Configure your local settings by copying affiliates/settings/local.py-dist to affiliates/settings/local.py and customizing the settings in it:

   $ cp affiliates/settings/local.py-dist affiliates/settings/local.py

   The file is commented to explain what each setting does and how to customize them.

5. Download the latest product_details JSON files:

   $ python manage.py update_product_details

6. Initialize your database structure:

   $ python manage.py syncdb
   $ python manage.py migrate

7. Install Stylus. If you have npm set up, just run:

   $ npm install -g stylus

Running the Development Server¶

You can launch the development server like so:

$ python manage.py runserver

Localization¶

If you want to set up localization, check out the locale repo using svn:

$ git svn clone https://svn.mozilla.org/projects/l10n-misc/trunk/affiliates/locale/ locale
# or
$ svn checkout https://svn.mozilla.org/projects/l10n-misc/trunk/affiliates/locale/ locale

Developing the Facebook App¶

If you want to work on the Facebook app side of Affiliates, you’ll need to create a development app on Facebook using your Facebook account.

1. Visit https://developers.facebook.com and click the Apps menu item in the top bar.
2. Click the “Create New App” button (might be slightly different if you haven’t created an app before).
3. Give your app a name and unique namespace, like username_fxaffiliates.
4. On the following App Basic Details page, check the “App on Facebook” option. Your settings will most likely be:
   • Canvas URL: http://localhost:8000/fb/
   • Secure Canvas URL: https://localhost:8000/fb/
   • Canvas Width: Fluid
   • Canvas Height: Fluid
5. Edit settings/local.py. There should be several settings that start with FACEBOOK that you will need to fill in.

Once the above is done you should be able to start your development server and view your test Facebook app.