Overview: --------- The ad_actions module provides triggers for the following advertisement events: - an advertisement has been clicked - an advertisement has been approved - an advertisement has been activated - an advertisement has been denied - an advertisement has been marked as pending - an advertisement has been taken offline - an advertisement has been created - an advertisement has been updated - an advertisement has been deleted - an advertisement has expired - an advertisement has an approaching scheduled activation - an advertisement has been activated through scheduling - an advertisement has an approaching scheduled expiration - an advertisement has expired through scheduling The triggers can be configured to cause any of the following actions: - generate an email - display a custom message to the user - override the ad's redirect Two advanced actions are provided by this module. The first is named 'Send e-mail before automated ad trigger', and can be used to send emails before an advertisement is scheduled to be activated or expired. The second is named 'Send e-mail on or after ad trigger' and can be used with any of the triggers defined by this module. This module depends on the token module, allowing you to create dynamic notifications. Permissions: ------------ In order to configure ad triggers, users must be in a role that has the 'administer ad triggers' permission. Examples: --------- This documentation offers two examples of how you can use the triggers and advanced actions provided by this module. It also explains how you can provide per-user configuration options for disabling notification emails. Click notification: ------------------- The following example shows you how to send an email to the owner of an advertisement whenever the advertisement is clicked. In this example, we configure the action to send no more than one email in every 24-hour period. Part I) ------- 1) Go to Administer >> Site configuration >> Actions and in the "Make a new advanced action available" section toward the bottom of the screen select "Send e-mail on or after ad trigger" from the drop down menu and click Create. 2) Enter something descriptive in the description field, for example you could enter "Send email after advertisement is clicked". 3) Enter "[owner_email]" in the Recipient field. This is a token that will automatically be replaced when the notification is sent. For a complete list of available tokens click the "Placeholder tokens" link. 4) Enter "Ad [title] has been clicked" in the Subject field. 5) Enter the following into the Message field: Hello [owner_name], Your advertisement has been viewed [today_impressions] times and clicked [today_clicks] times today. - The [site-name] team. 6) Set the 'When to send' field set to '1 day after'. 7) Click the 'Save' button. Part II) -------- 1) Go to Administer >> Site building >> Triggers and in the "After an advertisement has been clicked" section click the "Choose an action" menu and select the action you created in Part I above. 2) Click the 'Assign' button. With the above action defined and assigned to the click trigger, once an advertisement is clicked a notification to the ad's owner is added to a queue. If the advertisement is clicked again during the next 24 hours no additional notification is added to the queue. 24 hours after the ad was first clicked, the notification email is sent out. The token replacement happens when the email is sent, so all subsequent clicks are reflected in the notification email. Allowing users to disable notifications: ---------------------------------------- It is possible to allow individual users to disable the notifications generated by the advanced actions defined by this module. Part I) ------- 1) Enable the profile module, which is part of the core Drupal installation. 2) Go to Administer >> User management >> Profiles and click "checkbox" under the 'Add new field' heading. 3) Enter 'Advertisements' for the Category. 4) Enter 'Disable click notifications' for the Title. 5) Enter 'profile_disable_click_notifications' for the Form name. 6) Enter 'Check this box to disable click notification emails. When this box is unchecked, you will receive email notifications once every 24 hours when your advertisements are clicked.' 7) Set the Visibility to 'Private field, content only available to privileged users.' 8) Click 'Save field'. Part II) -------- 1) Go to Administer >> Site configuration >> Actions and click 'configure' next to the advanced action you created in the above example. 2) Scroll down and select 'Disable click notifications' for the 'Profile field used to disable notifications' (This option will only be visible after you have enabled the profile module and created at least one user profile field. 3) Click 'Save'. Part III) --------- 1) Users with proper permissions can now click 'My account' in the navigation block, then click the 'Edit' tab, and finally click the 'Advertisements' subtab. On the subsequent screen they can disable notification emails for their account. The above is just one example of how you may allow users to disable notifications. You may wish to use something other than a checkbox for the user's profile field -- the field type is not important, though notifications will only be disabled when the user sets the field to a non-empty non-zero value. You can re-use the same profile field with multiple actions, thereby providing a single checkbox to disable all notifications. Or, you can create a unique profile field for each advanced action providing your users with more granular control over the notification emails. It would be a good idea to explain to your users how they can disable notifications in each notification email that is sent. Notify that an ad is about to expire: ------------------------------------- The following example shows you how to send an email to all owners of an advertisement 1 week before the advertisement is scheduled to be automatically expired. Part I) ------- 1) Go to Administer >> Site configuration >> Actions and in the "Make a new advanced action available" section toward the bottom of the screen select "Send e-mail before automated ad trigger" from the drop down menu and click Create. 2) Enter something descriptive in the description field, for example you could enter "Send email 1 week before advertisement expires." 3) Enter "[all_owner_emails]" in the Recipient field. This is a token that will automatically be replaced with a list of all email addresses for all owners of a given advertisement when the email is generated. For a complete list of available tokens click the "Placeholder tokens" link. (The [ad_owner_emails] token is only available if you have enabled the ad_owners module.) 4) Enter "Ad [title] will expire in 1 week" in the Subject field. 5) Enter the following into the Message field: Hello [owner_name], To date, your advertisement has been viewed [global_impressions] times and clicked [global_clicks] times. Your advertisement will expire in about 1 week, on [autoexpire_large]. - The [site-name] team. 6) Set the 'When to send' field set to '1 week before'. 7) Click the 'Save' button. Part II) -------- 1) Go to Administer >> Site building >> Triggers and in the "Scheduled expiration" section click the "Choose an action" menu and select the action you created in Part I above. 2) Click the 'Assign' button. With the above action defined and assigned to the scheduled expiration trigger, a notification email will be sent to all of the ad's owners 1 week before it will expire.