Firefox Affiliates¶

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 settings/local.py-dist to settings/local.py and customizing the settings in it:

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

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

5. Initialize your database structure:

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

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.

Adding Banners to the Affiliates Mothership¶

Before adding a Banner to Affiliates, you must have the following:

• A display name for the Banner, as well as for the Category and SubCategory if they are new. These must be localized (typically by adding them to apps/shared/strings.py and extracting them normally) in each locale you want the Banner to be available in.
• The URL for the Banner to redirect to.
• A preview image for each locale the banner will be available in, sized to 150x125 pixels.
• The actual images to use for the Banner.

To add a Banner to the site:

1. Click on the Banners link under the Banners section of the admin interface.
2. If you are adding a new locale to an existing Banner, click the Banner’s name in the list of Banners and skip to step 4. If you are adding a completely new banner, click “Add Banner +” in the top right of the screen.
3. Fill in the details for the banner, including name and SubCategory. If you don’t want the banner to be live yet, uncheck the Displayed checkbox.
4. Add the preview images and banner images for each locale you want to add. You can add more locales using the “Add another ...” links at the bottom of each list.
5. Click the save button to submit your changes and save the banner to the database.

Always make sure to test that your new banner works and is available in the locales you specified after saving, and that the banner name and images are being localized correctly.

Adding Banners to Affiliates Facebook¶

Before adding a Banner to the Facebook app, you must have the following:

• The URL for the Banner to redirect to.
• Localized alt-text for the banner (typically stored in apps/facebook/templates/facebook/strings.html for localization).
• A default (en-US) banner image and thumbnail to use. Banner images are 300x216 pixels, thumbnails are 100x72 pixels.

To add a Banner to the app:

1. Click on the Facebook banners link under the Facebook section of the admin interface.

2. If you are adding a new locale to an existing Banner, click the Banner’s name in the list of Banners and skip to step 4. If you are adding a completely new banner, click “Add Banner +” in the top right of the screen.

3. Fill in the details for the banner, including the Banner name (never shown to users), link, and alt text (this must exactly match the English text submitted for localization).

   For the default image and thumbnail fields, use en-US images and do not add an en-US locale in the locale list.

4. Add the thumbnail and banner images for each locale you want to add. You can add more locales using the “Add another Facebook Banner Locale” link at the bottom of the list.

5. Click the save button to submit your changes and save the banner to the database.

Always make sure to test that your new banner works and is available in the locales you specified after saving.

Adding 3.6 Upgrade Banners¶

There is a special type of banner called a 3.6 upgrade banner. These banners show a different image depending on whether the visitor is using an up-to-date version of Firefox or not. Adding these banners requires a code change to update the list of 3.6 banners in the settings.

Adding these is kind’ve annoying, and hopefully will be made easier in the future.

Before adding a 3.6 Upgrade Banner, you must have the following:

• The hashes that will be generated for the banner images you’re going to add. The banners.models.rename function shows how this hash is generated.
• A preview image for each locale the banner will be available in, sized to 150x125 pixels.
• Three different images for each locale:
  • An image for when a user needs to update, called the update image.
  • An image for when the user is on the latest Firefox, called the latest image.
  • A split image to show to users when generating the banner that shows both of the images above, called the split image.

To add a 3.6 Upgrade Banner:

1. Add the hashes to the BANNERS_HASH setting in settings/base.py.
2. Add the split image and update images to the media/static_banners/ directory. The split image filename should look like hash.from_affiliates.png while the upgrade image filename should look like hash.upgrade.png.
3. Commit and push your changes.
4. Once the changes are pushed, add the latest image as a banner image on the Banner in the Affiliates admin. Double check that the filename generated by the site matches the hash that you used for the other images.
5. Save the banner.

Always make sure to check that the correct images are showing up for the 3.6 Upgrade Banner. The split image should appear during banner generation, and the other two images should appear when embedding the image based on your browser version.