The ad manager module relies on provider modules to serve ads from various ad networks. The documentation below will detail the steps required in creating an ad provider.

If you are not yet familiar with how the ad manager module works it is recommended that you read the documentation.

Contents

  1. Module basics
  2. Tell ad manager you supply a provider
  3. Create ad provider settings form
  4. Rendering ad units
  5. Global settings form
  6. Summary

Module basics

  1. Pick a machine name for your provider, this should consist of lowercase and underscore characters only. For the purposes of the rest of this documentation we'll use my_module, you should replace this with your module's machine name.
    If you plan to contribute your provider to Drupal.org read the information available on full projects and be sure to use a machine name that is not in use by another project by attempting to visit http://drupal.org/project/my_module.
  2. Create a new folder for your module, using your module's machine name, in the modules directory (either sites/all/modules or sites/[site directory]/modules).
  3. Create three files in your module's directory: my_module.info, my_module.install, and my_module.module
  4. In my_module.info place the following:
    name = Full name of my module
    description = Description about my module.
    core = 7.x
    dependencies[] = ad_manager
    package = Advertising
  5. In my_module.install place the following:
    <?php
    
    /**
     * @file
     * Install, update, and uninstall function for my module.
     */

    You can use this file for adding install, uninstall, update, enable, and disable hooks. For our basic example it will be left in this state.

  6. In my_module.module place the following:
    <?php
    

    This file will have content added to it for making our provider through the rest of the documentation. <?php will remain the first line of the file.

Tell ad manager you supply a provider

In my_module.module the hook, hook_ad_manager_providers(), needs to be implemented so that ad manager knows about your provider.

Insert the following code into my_module.module:

/**
 * Implements hook_ad_manager_providers().
 */
function my_module_ad_manager_providers() {
  return array(
    'version' => 1,
    'provides' => array(
      // The key 'my_module_provider' acts as the callback function for the
      //configuration form, and as the theme output name.
      // Do not wrap the value in t() as it is cached and will be wrapped with
      // t() on output.
      'my_module_provider' => 'My module provider',
    ),
  );
}

Create ad provider settings form

Ad manager allows you to create your ad provider settings form, the form that allows permissioned users to configure individual ad units, by creating a function that matches the key used in hook_ad_manager_providers(). In this case our key is my_module_provider.

/**
 * Ad Manager ad provider form for My module provider.
 */
function my_module_provider(&$form, &$form_state) {
  // Put previously stored settings in a short variable for ease of use.
  // Notice the storage of settings within a key matching the provider's key,
  // this allows the permissioned user to toggle ads between providers
  // without having to re-input settings configuration.
  $settings =& $form_state['item']->settings['my_module_provider'];

  // Create a select form element allowing the user to specify the number of
  // lines the ad unit should display.
  // This is just an example, your form should define form elements that 
  // configure settings for your ad network's ads.
  $form['lines'] = array(
    '#type' => 'select',
    '#title' => t('Lines'),
    '#options' => drupal_map_assoc(array(t('1'), t('2'), t('3'))),
    // We check if we already have a stored setting for lines, if so we use that,
    // otherwise we set a logical default value.
    '#default_value' => isset($settings['lines']) ? $settings['lines'] : '3',
  ),
}

/**
 * Ad Manager ad provider form validation for My module provider.
 */
function my_module_provider_validate(&$form, &$form_state) {
  // Form validation can be added here, this function is not mandatory.
}

/**
 * Ad Manager ad provider form submit for My module provider.
 */
function my_module_provider_submit(&$form, &$form_state) {
  // Put previously stored settings in a short variable for ease of use.
  // At the end of this function $settings will be stored by Ad Manager, there's
  // no need for you to create database tables or use variable_set()s to store
  // the ad's configuration.
  $settings =& $form_state['item']->settings['my_module_provider'];

  // $form_state['values'] contains the data submitted on our form.
  // We store our lines form element's selection in the $settings array.
  $settings['lines'] = $form_state['values']['lines'];
}

If you've never worked with Drupal's form API before you should take a look at the reference sheet, another great resource is the form_example module in the examples module.

Rendering ad units

To render your ad units ad manager will call:

// $name will be the ad unit name the permissioned user defined for the unit.
// $settings will be the settings array you stored in my_module_provider_submit().
// $index will be an index key, starting at 0, for the number of times this ad unit
// has been displayed on the page.
theme('my_module_provider', array('name' => $ad_unit_name, 'settings' => $settings, 'index' => $index);

To make theme('my_module_provider') accessible you need to first implement the theme hook, hook_theme(), to define the my_module_provider theme function.

Place the following in my_module.module:

/**
 * Implements hook_theme().
 */
function my_module_theme($existing, $type, $theme, $path) {
  return array(
    'my_module_provider' => array(
      'variables' => array('name' => NULL, 'settings' => NULL, 'index' => NULL),
    ),
  );
}

Then you must define your rendering function, in my_module.module:

/**
 * Theme My module provider ad units for Ad Manager.
 */
function theme_my_module_provider($vars) {
  // Do whatever you want to here, you can return HTML, attach Javascript, etc.

  // Fetch the lines setting for the ad.
  $lines = $vars['settings']['my_module_provider']['lines'];

  // Return some output for the ad unit. This could be 
  return t('This ad has been configured for %lines lines.', array('%lines' => $lines);
}

For an example of an ad manager provider that sets Javascript in the <head> tag for all of the elements on the page, take a look at the AdSense Custom Search Ads module.

Global settings form

If your ad provider would need settings to be defined globally, such as an account key for the ad network, you need to implement one more hook to create the form:

/**
 * Implements hook_form_FORM_ID_alter().
 *
 * Alter global Ad Manager settings form to provide needed configuration.
 */
function my_module_form_ad_manager_settings_form_alter(&$form, &$form_state) {
  // Create a fieldset for the provider to wrap any fields we will add, this
  // form is shared with any other providers that add their own settings to it.
  $form['my_module_provider'] = array(
    '#type' => 'fieldset',
    '#collapsible' => TRUE,
    '#title' => t('My module provider'),
  );

  // Add a field for the ad network's account key.
  $form['my_module_provider']['key'] = array(
    '#type' => 'textfield',
    '#title' => t('Network identifying account key),
    '#description' => t('e.g. 1235BA890'),
    '#default_value' => variable_get('my_module_provider__key', ''),
    '#required' => TRUE,
  );

  // Tell the form to use your submit function.
  $form['submit']['#submit'][] = 'my_module_provider_settings_submit';
}

/**
 * Ad Manager settings form submit handler for My module provider.
 */
function my_module_provider_settings_submit(&$form, &$form_state) {
  // Save the entered key.
  variable_set('my_module_provider__key',
      $form_state['values']['my_module_provider']['key']);
}

Summary

Although the above code consist of a lot of details there are really only three steps required for creating an ad provider:

  1. Implement hook_ad_manager_providers()
  2. Create ad provider settings form
  3. Theme ad unit output

Once your provider is complete and if you contribute it back to Drupal.org as a full project please create an issue in the ad manager issue queue requesting for the provider to be added to the project page's list of providers. Be sure to set the issue's component field to: Add provider to list