Maybe you'd like to begin with the Quick Start Guide which lists common "I want to do..." scenarios with AWPCP?
Installing AWPCP
Initial Setup
After installing AWPCP, you will see a Classifieds section of your WP Admin panel (usually on the lower left) that looks something like this (you may be missing the "XML Sitemap Options" until you download the AWPCP XML Sitemap plugin to go with it):
The very first and most important thing you need to do after installation is to click on "Settings". This will take you to the Classified Pages section of AWPCP's administration.
You should change the name of these pages as you wish them to appear on your site and then click "Save Settings". That will create the basic structure used by AWPCP and allow you to see it on the front end of your website. You can always go back and reset these names any time you like. But in order to see AWPCP working on the user-facing side of your website, you must save the page names at least ONCE.
AWPCP Administration Panel
The Admin panel of AWPCP consists of 7 standard and several optional items (1 displayed here):
(you may be missing the "XML Sitemap Options" until you download the AWPCP XML Sitemap plugin to go with it):
Settings: Manage the overall configuration of AWPCP
Fees: Create and delete fee plans to charge your users if you have a paid classified board. Can be ignored for a free board.
Categories: Where you go to manage the categories used in displaying ads within AWPCP.
Listings: The admin panel for handling ads--flagging, spamming, deleting, and managing images. You can also edit and create ads here as well
Import: CSV-based data importer to allow you to populate AWPCP from somewhere else
Debug: Useful if you post a support request. Gives us a snapshot of your settings immediately.
Uninstall: One way to uninstall AWPCP if you find it's not what you need. The other is through the Plugins panel.
Admin: Settings
The settings screen of AWPCP consists of several different groups of settings within AWPCP:
Each tab represents a category of settings:
General: Overall settings used by AWPCP that don't fit anywhere else
Classified Pages: The names of the pages used by AWPCP to manage and show ads from the user side.
Ad/Listing: Settings relating to ads and the listings like layout, notifications, etc.
Image: How images are handled in your classified site. Min/max width/height, file size, base images allowed, etc.
Payment: PayPal, 2Checkout configuration to handle payment processing
AdSense: Configuration for any Google AdSense ads you wish to display in your classifieds
Form Field: Allows you to show/hide the default ad fields for Place Ad, Edit Ad, and Show Ad
Registration: Settings around whether you want users to be registered with your site or not before using your classified board
Email: Template for emails sent to users during classified events (ad posted, expired, renewed, payment failed, etc). SMTP settings for overriding default WP mail if needed.
Settings: General
The General tab handles a number of important configuration items for AWPCP. The tab is broken down into several subsections for easier reading.
Here are some screenshots and explanations of the settings:
The General section handles these important functions:
- Turn on Translation File: This is required if you want to use AWPCP's PO file (language string externalization file). This tells WordPress to look for AWPCP_<language>.po in the another-wordpress-classifieds-plugin directory.
- Show listings on main page: If you check this box, the "main page" (the one labeled "AWPCP" by default, the parent of all other pages for AWPCP) will show ads instead of categories. Uncheck if you wish to show categories instead (default).
- Category columns on view page: Sets the number of columns of categories you want to display on your main classifieds page. Valid values are 1-5, default is 2.
- Welcome message: This is the message displayed at the top of the main classifieds page. If you are translating AWPCP into your language, be sure to change this value as well.
- Role of admin users: AWPCP allows you to set who can see the admin panel for AWPCP. By default it's set to "admin", but you can enable it for editors as well.
- Enable Page Filter: This hides all AWPCP-created pages from the front end from your menu. Most of the time you probably want to hide only some of the pages (e.g. Payment Thanks, Payment Cancel, Renew Ad, Edit Ad) as these pages are used only in certain circumstances. This is best done through your theme and page exclusion filters.
- Show AWPCP latest news: This enables the RSS feed from awpcp.com so you can stay abreast of updates from us. Good to keep it on to know when an update is released.
Terms of Service:
- Display and Require ToS: Checking this will force users to see and accept a Terms of Service from you on the Place Ad form. If you disable this, no terms will be shown.
- Terms of Service (textbox): This can be used two ways. 1) You can put in any text you like here regarding your restrictions for posting classifieds. OR 2) You can put in an URL here to an existing page (starting with http) and it will automatically create a link to that page instead of the text box.
Anti-SPAM: These are settings relating to Akismet integration
- Use Akismet: If you turn this on, you must have Akismet installed. If you don't, an error will occur. (Recommended to turn ON to reduce spam)
- Enable math captcha: Puts a simple math problem at the bottom of the Place ad page to foil robots from posting ads
- Max number used in Math captcha: For the addition problem (X + Y), this setting is the maximum value used for either X or Y during generation. Default is 10 (meaning X and Y will each be smaller than 10).
Window Title: These settings handle the display of the <title> tag for AWPCP pages.
- Title separator: What to use in between items, such as dash, slash or pipe. Default is dash (-)
- Show "X" in title? Checking this will allow for X to show in the title. By default, all items are available to the title: city, state, country, county (if used), and category.
Widget: AWPCP uses various widgets (Search, Latest Ads, and if you have it installed, Featured Ads) to display information. Some themes use different wrapper tags for their widgets than others. This allows you to change those wrappers to match your theme.
SEO Settings: If you want to use URLs of the form /something/like/this instead of /something?like=this, which Google prefers, then you need to check this option AND set a non-default permalink option (we suggest /%category%/%postname%/, but anything that isn't one of the defaults will do nicely)
User Ad Management Panel: Checking this option will turn on the Ad Management panel for all WP profiles on your site. That means a registered user can see and manage all of their posted ads in a single place. Turning this option on automatically turns on "Require Registration" as you must have registered users to take advantage of this setting.
Settings: Classified Pages
The Classifieds Pages tab is where you define the names (and implicitly, the page slugs) of all AWPCP-created pages.
AWPCP uses the pages created here to manage the various aspects of your classified ads. For each created page, a shortcode is added to the page which then outputs the AWPCP classifieds content for each page in the appropriate way.
The names shown here are the default names for the pages. You can (and probably should) use something different for these page names, particularly the top-level page ("AWPCP Main page"), named AWPCP by default.
After making any changes, be sure to click "Save Settings" at the bottom of this page.
ALL of these pages are required by AWPCP and deleting any them is very, very bad. If you do that, AWPCP will not work as expected. Luckily, if you accidentally delete them, it's easy to get them back. Make sure you have all page names filled out and then click "Restore Pages" at the top of this tab.
IMPORTANT: You should do ALL page management for these pages in this tab ONLY. Doing any work with them in the WP Pages admin section can break AWPCP in subtle and odd ways.
Settings: Ad/Listings
This tab represents most of the settings revolving around the ads themselves.
Notifications: This section represents what kind of email notices you want sent out with AWPCP. You (the admin) can be notified of the following:
- New ads posted
- Ad expired
Users can be notified of:
- Posted ads
- Expired ads
- Expiring ads (giving them a chance to renew). You can set the threshold when you want these renew emails to go out in days.
Moderation: This section controls how you want to handle ads after items are posted. You can do the following here:
- Only admin can post ads: Prevents the Place Ad link from working and displaying. Only you (admin) can post anything.
- Disable ad until admin approves: Once an ad is submitted, you must Approve it in the Listings panel or the Ad Management panel. Great way to moderate Free classified boards.
- Waiting Approval Message: What gets displayed to the user if you have "Disable ad until admin approves" selected after the user posts their ad.
- Prevent ads from being posted in top level categories: This keeps the ads in subcategories. For example, if you have a "For Sale" top category, and under that category you have "Cars", "Trucks" and "Trailers" as subcategories, turning this option on will prevent users from posting in "For Sale", but not the others.
- Enable paid ads that are pending payment: Automatically approves ads for a paid classified board, even when you're not sure of the payment status. Turning on this option allows people who paid but are awaiting eCheck approval to see their ad right away.
- Free ads expiration threshold: This number is the number of days you allow free ads to be posted in your board. 0 means "forever". If you are running a paid board, this option is completely ignored. See the section on Admin: Fees for how to configure a paid classified board.
- Disable expired ads instead of deleting them: Normally, when an ad expires, it is deleted from the database. If you would prefer to have these ads preserved, check this option instead.
Layout & Presentation: This section controls options regarding the display of pages and ads on the front end.
- Thumbnail width: The width of thumbnail images created by AWPCP during upload, displayed for the Browse Ads page.
- Allow HTML in ad text: Whether you permit full HTML in the Description field of the Place Ad page. Use of this option encourages some bad practices from spammers, including links and dangerous embedded Javascript. Use with great caution.
- Display this text above ad detail: On the Place Ad page, above the Description field, this text will be listed. By default, we populate it with "No HTML Allowed". You can customize this however you like.
- Maximum ad length: The number of characters that can be entered in the Description field for Place Ad.
Layout & Presentation: (continued)
- Ad Listing Page Layout: This is the HTML template, read by AWPCP and substituted at runtime with all of the data shown as field codes (e.g. $ad_title, which will substitute the actual Ad Title information submitted in the ad). You can change the order of this layout, or even use different fields, add your own custom CSS classes or styles to make the ad layout look the way you want. You can safely add, change or delete field codes in this template to suit your needs as long as they match the list below (and are supported for that view)--AWPCP doesn't require any of them to be present. The provided template is merely a suggestion--but the template must remain valid HTML (no broken tags, all tags must match). See valid field codes below.
- Single Ad Page Layout: The same as ad listing, but for the Show Ad page instead.
Translation note: If you are translating strings, you must translate these templates as well, since they contain English labels for fields.
Valid Field Codes for AWPCP
Listing Page:
$addetailssummary
$ad_title
$awpcpadpostdate
$awpcp_state_display
$awpcp_display_adviews
$awpcp_city_display
$awpcp_display_price
$ad_categoryname
$city
$state
Single Ad Page:
$ad_title
$featureimg
$codecontact
$adcontact_name
$adcontactphone
$location
$aditemprice
$awpcpextrafields
$awpcpvisitwebsite
$showadsense1
$addetails
$showadsense2
$awpcpshowadotherimages
$awpcpadviews
$showadsense3
$ad_startdate
$ad_postdate
$ad_categoryurl
$ad_categoryname
$city
$state
$country
$village
Layout & Presentation: (continued)
- Group ad listings by: Changes how you want the ads sorted by on the Browse Ads page.
- Group ad listings search results by: Changes how you want the ads sorted by on the Search Ads page.
- Default number of ads per page: The number of ads displayed on the Browse Ads and Search Ads page
- Limit search to available locations: If you use this option, AWPCP will attempt to build a list of locations used by previous ad posters for city, state and country (if you display those fields). However, if people enter garbage data (e.g. austin, Austen and Austin for the city "Austin, TX") it will display all options available. If you want true region limitations for ad posters and browsers, we suggest installing the Regions Control module instead.
- Show ad count in categories: On the Browse Categories and View Categories pages, the Category name is displayed. If you turn this option on, it will also list the number of ads in that category next to the name in parenthesis (e.g. "For Sale (12)"). Default is on.
- Show ad views: Whether to display the "This ad was viewed X times".
- Make URLs in ad text clickable: If someone uses "http://" in an ad, this setting will attempt to make it a clickable link if you turn it on. This is a setting you can turn on to allow people to put in additional links without the risk of full HTML usage (from the setting above). Use with caution, as spammers can really go crazy if they find your site.
- Add no follow to links in ads: Puts rel="nofollow" to your links which neutralizes the value of classified ads to spammers. Default is on (recommended)
Menu Items: Here, we control which links to display at the top of the Place Ad page. They are all enabled by default, but you can customize this however you like depending on your board's needs.
Settings: Payments
The Payments tab is where you setup your PayPal and 2Checkout gateways for accepting payments in exchange for posting ads on your site.
IMPORTANT: If you are using PayPal or 2Checkout in test mode, make sure you have the "Put payment gateways in test mode" checked. Conversely, when you are done with testing, make sure you are using your REAL PayPal or 2Checkout credentials and you turn off "Put payment gateways in test mode". Failure to do so will result in missed payments and possible strange errors.
Payment Settings: Where you activate a paid board
- Charge listing fee: This is the setting that turns on your AWPCP board for accepting payments. After you turn this on, you must configure your Fee plans to have at least one plan to charge users. If you have no plans, your users will not be able to post ads.
- Currency used in payment pages: This is the PayPal-allowed currency that will be displayed on your Show Ad and Place Ad pages. Standard currencies like the Euro, GBP, Yen and US Dollars will have the symbol automatically substituted. Other currencies, like the Australian Dollar will use this field value instead (e.g. AUD). NOTE: Not all currencies are supported by PayPal at this time. Since this data is sent to PayPal, only PayPal currencies are supported. However, if you are not using PayPal and want to display a currency (e.g. the South African ZAR).
- Put payment gateways in test mode: Puts PayPal and 2Checkout in "test mode" to use the sandbox/testing gateways instead of the real ones. Useful during configuration to verify payment processing through AWPCP. Make sure to turn it OFF when you're done testing!
PayPal Settings: PayPal configuration information
- Activate PayPal: Must be checked if you want to use PayPal as a payment gateway. Turn it off otherwise.
- PayPal receiver email: Your PayPal account used to accept payments. If you have "test mode" on (see above), this email should be your test account, rather than your real account.
- PayPal currency code: One of PayPal's valid currency codes (see below). Defaults to USD.
Valid PayPal currency codes recognized by AWPCP:
('AUD','BRL','CAD','CZK','DKK','EUR','HKD','HUF',
'ILS','JPY','MYR','MXN','NOK','NZD','PHP','PLN','GBP','SGD','SEK','CHF','TWD','THB','USD')
Recommended PayPal Account Settings
We recommend applying the following modifications to your PayPal account's settings to avoid problems during the checkout and payment steps.
Enable Instant Payment Notifications (IPN) notifications
- Login to PayPal.com.
- Go to the Profile section.
- Go to the My selling tools section.
- Look for Instant payment notifications in the list on the right and click Update.
- If you have never configured IPN before or they are currently disabled:
- Click Choose IPN Settings.
- If IPN are already configured:
- Click Edit Settings.
- Enter your website home URL in Notification URL field and choose Receive IPN messages (Enalbed).
- Click Save.
Disable Payment Data Transfer (PDT)
- Login to PayPal.com.
- Go to the Profile section.
- Go to the My selling tools section.
- Look for Websites preferences in the list on the right and click Update.
- Disable Auto Return (Set to Off).
- Disable Payment Data Transfer (Set to Off).
- Click Save.
Change language encoding to UTF-8
- Login to PayPal.com.
- Go to the Profile section.
- Go to the My selling tools section.
- Look for PayPal button language encoding at the bottom of the page and click the link.
- Click More Options.
- Set Encoding to UTF-8 and make sure to answer Yes to the question: Do you want to use the same encoding for data sent from PayPal to you (e.g., IPN, downloadable logs, emails)?.
- Click Save.
2Checkout Settings: 2Checkout configuration information
- Activate 2Checkout: Must be checked if you want to use 2Checkout as a payment gateway. Turn it off otherwise.
- 2Checkout Account: Your 2Checkout account used to accept payments. If you have "test mode" on (see above), this should be a test account instead of your real account.
Settings: Image
This tab controls how AWPCP uploads, resizes, crops and validates images associated with ads.
Image Settings: The following options are supported
- Allow images in ads: Turn this off if you don't want to allow images in yours ads. Default is on. This setting affects both free and paid classified boards.
- Hide images until admin approves them: If you would prefer to moderate ads with images to verify content before displaying it, check this box. You will then need to approve the ad in the Listings view.
- Turn off Thickbox/Lightbox: This will disable the Lightbox effect (where the browser dims and displays an image in a larger size with a small border around it) if you check it. Some themes install a lightbox that doesn't work well with AWPCP. This will shut it off.
- Number of images allowed in free mode: The maximum number of images that can be posted on a FREE classified ad (only). To configure paid image counts, you must setup fee plans instead.
- Uploads folder name: The folder used by AWPCP to store images. It will be created under /wp-content/ in your WP install. NOTE: If you are having trouble uploading images, check the permissions on this folder. They should be at least 755 (drwxr-xr-x).
- Maximum file size per image: The largest size of image you will accept, in bytes. WordPress has a default 2MB image upload limit unless you configure it to be higher, so keep that in mind if you put in large numbers that don't seem to work. This is often a webhost setting.
- Minimum file size per image: The smallest filesize of image you will accept, in bytes.
- Minimum image width/height: The minimum size dimension you will accept for an image. 125 is the default, which is a reasonable thumbnail size.
- Max image width: The widest the uploaded image can be, in pixels
- Max image height: The tallest the uploaded image can be, in pixels.
Settings: AdSense
The AdSense tab controls the placements of your AdSense blocks inside of the Show Ad and Browse Ads pages for AWPCP.
Keep in mind that using AdSense on your AWPCP classifieds may cause your classifieds to be "blocked" by browsers that have ad blocking software enabled.
AdSense Settings:
- Activate AdSense: Turn this on if you want to output your AdSense code in the Browse Ads and Show Ad pages.
- AdSense code: The Javascript/HTML code from Google's AdSense generated ad unit. The layout is automatically setup for 468x60 "banner ads", but you can change the layout however you like to handle it for other sizes.
- Show AdSense at position: This tells AWPCP where you want to put the banner--position 1 (above the ad text/body), position 2 (under the ad text/body but above the images) or position 3 (below the ad images).
Settings: Form Field
The Form Field tab controls the display of the "standard" ad fields, such as city, state, and country. You can configure whether such fields are visible and/or required in the Place Ad form.
Form Field Settings:
- Show [field]?: This will turn on the field in both the Place Ad form AND the Show Ad form
- Require [field]: This will perform a validation on the field on Place Ad and Edit Ad, and if the field is not present, will generate an error as the user attempts to save the form.
Settings: Registration
Controls the registration settings for AWPCP. Registration in this context means whether someone must be a registered user on your WordPress site to perform certain actions in AWPCP.
Registration Settings:
- Require user registration: Turn this on if you want only users with accounts on your site to post AWPCP ads. Note: If you activate 'Turn on Ad Management Panel" under General settings, this option will be enabled automatically.
- Reply to Ad requires user registration: Turn this on if you only want registered users to reply to your AWPCP ads. Helps reduce spam to your posters.
- Post login form to: The full URL of your login page to WP. 99.9% of the time you don't need to use this, as finding this page is easy to do by AWPCP. If you have some custom plugin that alters your login page location, you can override it here.
- Location of registration page: Similar to the URL above, only required if you are using a plugin that has some mod-rewrite change to the login URL. 99.9% of users will never need to change this.
NOTE:. If you turn on registration in AWPCP, your site must also allow users to register in the first place. This is a WordPress setting that you can find under Settings->General. Look for the Membership field and make sure "Anyone can register" is checked. If it is not, your users will be unable to post Ads if you require registration!
Settings: Email
The email tab allows you to configure the email templates sent to your users for the notifications you configured under Ad/Listing settings.
General Email Settings:
- Use sender email for reply messages: By default, AWPCP will use the admin email of your WordPress blog to use for emails sent out. If you want your emails from AWPCP to appear from someone else, check this option (with the caveat mentioned in the image above--Mail servers today are very picky about spam and sending email from joe@hotmail.com from a site called foo.com will trigger spam filters in most cases.) Use with caution
- FROM email address for outgoing mails: If you check the prior option, this is the email that will be used instead.
Ad Posted Message: If you turned on the user's notification to receive an email when their ad was posted in Ad/Listing settings, this is the email template used for the message.
- Subject for Ad Posted By: The subject line of the email sent when a user is sent the "Ad Posted" notification.
- Body for Ad Posted By: The body of the email sent when a user is sent the "Ad Posted" notification.
Reply to Ad Message: AWPCP uses a Craigslist-like notification system. The poster's email is never displayed to the end user. Only when the person browsing the ad clicks on the Contact link from the Show Ad page can they contact they poster, and only through a form they submit on your site. The ad poster will then receive this email template.
- Subject for Reply to Ad: The subject line of the email sent when someone uses the Contact link from the Show Ad page.
- Body for Reply to Ad: The body of the email sent when someone uses the Contact link from the Show Ad page.
Request Ad Message: This section has to do with requesting an ad access key. Ad access keys are used to edit ads when you have Ad Managememt panel turned off under General settings.
- Subject for Request Ad Access Key: The subject line of the email sent when someone uses the Edit Ad link from the Show Ad page. The email will ONLY be sent to the original poster of the ad.
- Body for Request Ad Access Key: The body of the email sent when someone uses the Edit Ad link from the Show Ad page.
Incomplete Payment Message: If you have a paid classifieds board and there is a problem during the payment phase of placing an ad, this is the email template used to notify the user of that problem.
- Subject for Incomplete Payment email: The subject line of the email sent when someone has a payment problem during the Place Ad workflow.
- Body for Incomplete Payment email: The body of the email sent when someone has a payment problem during the Place Ad workflow.
Ad Expired Message: If you turned on the user's notification to receive an email when their ad expired in Ad/Listing settings, this is the email template used for the message.
- Subject for Ad Expired email: The subject line of the email sent when a user is sent the "Expired Ad" notification.
- Body for Ad Expired email: The body of the email sent when a user is sent the "Expired Ad" notification.
Renew Ad Message: If you turned on the user's notification to receive an email when their ad is about to expire (within the expiry threshold) in Ad/Listing settings, this is the email template used for the message.
- Subject for Renew Ad email: The subject line of the email sent when a user is sent the "Renew Ad" notification.
- Body for Renew Ad email: The body of the email sent when a user is sent the "Renew Ad" notification.
Advanced Email Configuration: These settings should only be used when your WordPress site doesn't seem to want to send email via the standard WP mail functions. This allows you to specify SMTP settings for an email server. If you use these settings, AWPCP will use them instead of the standard WP mail functions. Use with care.
- Enable external SMTP server: Turn this on to use the SMTP settings instead of your default WP mail functions.
- SMTP host: The server or IP address of your SMTP server
- SMTP port: The SMTP port of the server. Defaults to 25.
- SMTP username: The login used to send mail
- SMTP password: The password of the login name above.
IMPORTANT--please read concerning Facebook integration (updated Oct 3, 2018)
Facebook Integration
We currently support two methods for posting new ads to Facebook: Facebook API and Zapier/IFTTT Webhooks.
Support for Facebook API will be removed in the future. Facebook significantly reduced access to their APIs across all apps on April 4, 2018. Now it takes longer and is more difficult to configure Facebook Apps that can post content to pages or groups. As a result, it is unlikely that this integration is going to work for new users. We introduced support for Zapier/IFTTT Webhooks as an alternative and expect customers to migrate to that integration method.
You can read more about Facebook changes here: https://developers.facebook.com/blog/post/2018/04/04/facebook-api-platform-product-changes/
If you are currently using the Facebook API integration method and not having any issues, you don't have to do anything right now. If you are having issues, please read the Common Problems and Solutions section at the bottom to try to fix them.
App Review
As of April 4, 2018, all applications need to go through App Review in order to get access to the Page API and Groups API. That means that you may need to submit your app for review (ask for the manage_pages, publish_pages, publish_to_groups permissions), before AWPCP can display the list of pages and groups you manage and be able to post classifieds ads to those groups and pages.
Integration with Facebook API
Application Configuration
This integration requires admin users to create a Facebook App in https://developers.facebook.com/apps/ or use an existing application they control.
Create a Facebook App
If you already have an App that you want to use with AWPCP, skip this section.
- Visit the Apps section in Facebook for Developers and click the Add New App button:
- Fill the required information:
Enter the name of your app (the name of your website, for example) and a contact email. - Once the app is created, you will be redirected to the Product Setup page:
Find the Facebook Login product and click the Set Up button. - Find the Settings link under Facebook Login on the left sidebar and click it:
- Fill the Valid OAuth Redirect URIs field with the URL shown at the top of Facebook Settings on AWPCP.
- Now click Save Changes and then find the Settings link right under Dashboard, at the top of the left sidebar.
- When you click the link a menu should expand with Basic and Advanced links. Click Basic.
- On the Dashboard, take note of the App ID and App Secret, you will need to enter them both in AWPCP's settings.Copy the values to a temporary text field or go directly to the Facebook Settings section in AWPCP's Settings page and enter the values there.
Also, enter the domain of your website into the App Domains field. - Then, scroll to the bottom of the page and click the Add Platform button. That should open up a modal dialog, like the one shown below:
Click on Website. - A new section should have been added at the bottom of the screen, right above the Add Platform button. Enter the URL of your website in Site URL textfield and click Save Changes.
- Finally, click the OFF switch at the top of the page to take your app live:All new applications are in development mode. You should make your App public (live mode) so that the links and posts it creates, can be seen by everyone.Your application should now be live and ready to be used with AWPCP.
Enter Facebook App ID and App Secret in AWPCP's Settings
Go to AWPCP's Facebook Settings page and enter the App ID and App Secret for your App. If you created a new app, those are the values we mentioned in step 6 in the previous section. If you are using an existing App, just go to https://developers.facebook.com/apps/, chose you app and look for those values on the Basic Settings page:
Once you have entered both values, click the Save Changes button at the bottom of the page.
When the page is reloaded, a link to obtain an access token from Facebook will be available under the Facebook User Authorization section:
2. User Authorization
In order to post Ads to Facebook Pages and Groups, the plugin needs an access token to communicate with Facebook on behalf of the owner of those pages and groups. The User Authorization step is designed to help admin users get and configure an access token from Facebook.
The preferred method to get an access token is clicking the obtain an access token from Facebook link.
You will be redirected to Facebook and asked to give the application configured in the first step a series of permissions:
- Permission to read your public profile.
- Permission to post to Facebook on your behalf.
Please make sure you chose the appropriate audience for your posts. If you chose Friends, nobody outside of your group of Friends will be able to see or interact with the posts the plugin will create for you.Normally, Public is the value you want to choose in this step. That would let anyone on Facebook to see what you share. - Permission to manage your groups and pages.
After that, you will be redirected to the Facebook Settings page on your website and you should be able to see a sequence of characters in the User Access Token text field:
You will be asked to grant the permissions mentioned above only the first time you click the link. However, the process should always end with an access token being entered in the User Access Token field.
The third and final step of the configuration should be avaialble now as well, showing a list of Facebook Pages and/or Groups associated with the user whose Access Token was entered/generated here.
3. Page and Group Selection
The last step is to select one of the available Facebook Pages and/or Groups and click the Save Changes button:
You should be able to see the Pages listed in https://www.facebook.com/bookmarks/pages and the Groups listed in https://www.facebook.com/bookmarks/groups. Please make sure you open those inks while logged in Facebook as the user whose access token was configured before.
If your page or group is listed in Facebook but is not being shown in the Facebook Settings screen, then an error occurred during the configuration or you Facebook App doesn't have enough permissions approved. Try clicking the Diagnostics button above the General Settings section:
or repeat the configuration process again, paying special attention to any message displayed at the top of the page. Sometimes errors that cannot be handled automatically occurs; in those cases the plugin will detect them and provide feedback about what happen so you can correct the information entered, repeat the action or contact support, depending on the error.
Usage
General Settings
You can control whether Ads are posted to Facebook Groups and Pages manually or automatically from the General Settings sub-section:
If automatic posting is enabled, AWPCP will attempt to post an Ad shortly after it is posted and enabled. On the other hand, if automatic posting is disabled, you can post specific Ads to Facebook from the Listings section:
The Send to Facebook action will appear for every Ad that hasn't been posted to Facebook before and only if the Integration has been properly configured and at least a Facebook Page or a Group has been selected as destination.
You can also select multiple Ads and use a bulk action to send them to Facebook.
Changing the audience for your posts
The plugin does not control the visibility of posts created on behalf of users. To change the audience for your posts, you need to go into your Facebook account settings at https://www.facebook.com/settings?tab=applications and update the app's configuration:
You need to find the application that is using in the Facebook Integration section, in the plugin settings, and update the posts visibility:
- Put your mouse over the name of the application.
- A pencil icon should appear. Click it.
- A dialog will appear. Scroll to the top and change the selected value for App visibility and post audience to the desired value:
As explained in the screenshot, that's the setting that controls the audience for posts the app makes on your behalf. Normally you want to make your content available to as many people as possible, so choose Public to achieve that. However, if you have a reason to restrict access to your content, you can pick any of the other values available when you click on that dropdown.
Common Problems & Solutions
Only owners of the URL have the ability to specify the picture, name, thumbnail or description params.
If you receive an error that contains this message after trying to send a classified to a Facebook page or group, please make sure you are using AWPCP 3.8.6 or above. If you are using a newer version and still seeing that error, you may need to verify ownership of your domain on Facebook's Business Manager: https://developers.facebook.com/docs/sharing/domain-verification
Invalid Scopes: manage_pages, publish_pages, publish_to_groups
If you see the following error after trying to get a valid User Access Token:
Invalid Scopes: manage_pages, publish_pages, publish_to_groups. This message is only shown to developers. Users of your app will ignore these permissions if present. Please read the documentation for valid permissions at: https://developers.facebook.com/docs/facebook-login/permissions
You have to submit your Facebook Application for Review and ask for those permissions or use the Webhooks integration method to send ads to Facebook using Zapier or IFTTT Webhooks.
Requies publish_to_groups permission and app being installed in the group
If you see the following error trying to send ads to a Facebook Group:
(#200) Requires either publish_to_groups permission and app being installed in the group, or manage_pages and publish_pages as an admin with sufficient administrative permission.
Please make sure the Facebook Application was added to the group.
Facebook and Zapier Integration
Another WordPress Classifieds Plugin supports sending ads to Facebook using Zapier Webhooks. This document explains how to create a Zap for this purpuse and update the plugin settings to use it.
Prepare the plugin to interact with Zapier
- Set Zapier/IFTTT Webhooks as the selected Facebook Integration Method.
- Disable Send Ads to Facebook Automatically and Ask Facebook to clear cache for ads pages. We want the process to be manual during the creaton of the Zap. You can enable these features again at the end of the process.
Create a Zap
- Create or login to your Zapier account. Then go the Zap Editor.
- Choose Webhooks as the Trigger App:
- Select Catch Hook as the Trigger and click Save and Continue
- Skip the Pick off a Child Key setp by clicking Continue.
- Copy the webhook URL that appears on the Test step:
- Go to the Facebook Settings on AWPCP and paste the webhook URL as the value for the Zapier webhook used to send ads to a Facebook page setting. Then click Save Changes.
- Go to the list of ads on the admin dashboard and click the Send to Facebook action for the test ad you created before:
- Now go back to the Zap Editor and click the Ok, I did this button. You should see a list of at least one sample hook to choose. Expand the hook details to make sure it includes the information from the test ad:
Then choose a hook and click Continue. - Choose Facebook Pages as the Action App:
- Select Create Page Post as the Action and click Save + Continue:
- Chose a connected Facebook account or connect one using the Connect an Account button. Then click Save + Continue:
- Select the Facebook Page where you want to send the ads:
- Provide a message for the Facebook post. You can enter a custom message, use the title or description of the ad or a combination of those. Click the plus at the top right corner of the textarea to insert the titile or description of the ad:
- Select the URL of the ad as the content of the Link URL field. This is required if you want Facebook to load the thumbnail, title and description from the Open Graph meta tags included in the page of the ad:
- Once you have selected a Facebook Page, provided a message and a link URL, click Continue. Zapier should now show an example of the message that is going to be posted to the selected page:
Click the Send Test To Facebook Page button and wait for Zapier to show a confirmation message:Then check that the post was created on the selected page and click Finish. - To complete the proceess, provide a name for the Zap you just configured and turn it on:
Update plugin settings
- Double check that Zapier/IFTTT Webhooks is selected as the Integration Method.
- Enable Send Ads to Facebook Automatically if you want the plugin to send request to the webhook URL automatically.
- Enable Ask Facebook to clear cache for ads pages if yoiu want the plugin to ask Facebook to clear the cache it has stored for ads pages before trying to send a request to the webhook URL.
Facebook and IFTTT (If This Then That) Integration
Another WordPress Classifieds Plugin supports sending ads to Facebook using IFTTT Webhooks. This document explains how to create a Applet for this purpuse and update the plugin settings to use it.
Prepare the plugin to interact with IFTTT
- Set Zapier/IFTTT Webhooks as the selected Facebook Integration Method.
- Disable Send Ads to Facebook Automatically and Ask Facebook to clear cache for ads pages. We want the process to be manual during the creaton of the Applet. You can enable these features again at the end of the process.
Create an Applet
- Create or login to your IFTTT account. Then go the Webhooks Settings.If this is your first time using Webhooks on IFTTT, click the Connect button. You should be redirect to the same URL, but this time the page should show the webhook URL:
- Copy the webhook URL that appears on screen.
- Go to the New Applet screen:
- Click on +this and then find and choose the Webhooks service:
- Choose Receive a web request as the Trigger:
- Enter an Event Name and click the Create Trigger button:You can use any event name you want. Just remember to kepp that name at hand because we will use it later in the configuration.
- Click on +that and then find an choose the Facebook Pages service:
- Choose Create a link post as the Action:
- Click Add ingredient under the Link URL textfield and select Value1:
- Type a message, optionally using ingredientes from the event to customize the content.
The ValueN ingredientes from the event correspond to the following ad properties:
- Value1: The URL of the ad.
- Value2: The title of the ad.
- Value3: The descriptoon of the ad.
- Review your applet and click Finish:
- Go the Facebook Settings on AWPCP and enter the webhook URL from step 2 and the event name from step 6 as the value for the URL used to send requests to IFTTT Webhooks service and The name of the event that will be posted to the Webhooks service settings, respectively:
- Go to the list of ads on the admin dashboard and click the Send to Facebook action for the test ad you created before:
Update plugin settings
- Double check that Zapier/IFTTT Webhooks is selected as the Integration Method.
- Enable Send Ads to Facebook Automatically if you want the plugin to send request to the webhook URL automatically.
- Enable Ask Facebook to clear cache for ads pages if yoiu want the plugin to ask Facebook to clear the cache it has stored for ads pages before trying to send a request to the webhook URL.
Admin: XML Sitemap
The XML Sitemap tab displays the status of the AWPCP XML Sitemap configuration. Normally, there is little that needs to be done from this tab once the Google XML Sitemap Generator plugin and the AWPCP XML Sitemap plugin are both installed. The sitemap is automatically updated with new entries from AWPCP as they are added.
NOTE: If you find the Google is not indexing your ads, you may need to make the changes noted here in the FAQ article about the XML Sitemap plugin.
XML Sitemap Settings:
- When the plugin is properly installed, you should see two green "Installed" messages on the page. If either is red, you need to install the missing component.
- You can manually rebuild the sitemap by clicking on the "Rebuild Sitemap Now" but this is generally not required.
Admin: Extra Fields
Extra Fields is where you define the items that will be added to your individual ads' forms. They can be general or category specific fields.
Admin: Regions
Regions Control allows you to create standard regions, such as cities, states, countries, counties, villages, etc. and present the user with a drop down list for the Place Ad process instead of allowing free form text entry, which is difficult to search on.
Furthermore, Regions provides an important ability to filter listings based on selecting a particular region (state, city, whatever) by the user. Listings for a category, search result or the entire classified database will be filtered to that's user's chosen location, making their results relevant.
Configuring Regions
The FAQ has a good document on how to configure regions the right way the first time. Start with this article.
Admin: Fees
This section is where you configure the payment plans used to purchase classified ads for a paid classified site. If you are running a free classified site, you do not need to do anything here.
To configure a new fee plan, start by clicking the "Add New Listing Fee Plan" button at the bottom of the screen. This form will appear:
All fields are required. Enter the name of the plan (which will be displayed to the users when they place ads), the cost/price of the plan, the term/duration (how long an ad will be active on the site after being placed), as well as the Images allowed for an ad.
A typical configuration might be to have several plans with varying durations (like 30, 60, and 90 days) or plans with different images allowed for an ad (1, 2, or 4) or a combination of the two. You should try to keep it simple for your users. A user that easily understands what you're offering is a user that will quickly buy it if they like it.
To edit existing fee plans, select a plan that already exists from the Fees screen, like you see below:
Make any changes you want to the plan you wish to change--such as updating the price, the name, images allowed or the duration. After that, click "Update Plan" to save your changes. Make sure you click the Update Plan under the fields you JUST changed.
To delete a fee plan, find the plan you no longer need and click on "Delete Plan" to get rid of it.
Admin: Categories
This area is where you define the categories used for your classified ads. Categories help you organize your ads conveniently for users to browse desired areas of interest.
IMPORTANT: AWPCP does NOT share categories with WordPress. If you already defined WP categories that you want to use, you will need to redefine them in AWPCP. Conversely, defining AWPCP categories will not affect your WP posts or pages either.
AWPCP comes with a standard set of Classifieds categories which you are free to delete, add to, or modify to suit your needs. AWPCP supports a single parent/child hierarchy of categories. The parent categories are identified as "Top Level Categories" in the admin panel, while the children are those categories which have a parent.
When the category list is displayed in AWPCP, you may optionally display a count of ads next to the category, like so:
For Sale (12)
Parent categories will have a count of ads that is the sum of all their children, for example:
For Sale (12)
Electronics (5)
Cars and Trucks (7)
For Sale, being the parent category, has 7+5 total ads, or 12, as shown.
To create new categories in AWPCP, first go to this section of the Categories page:
Next, you need to enter a category name (required) and determine whether this is a Top Level Category or a child category. If it's a top level category, select the option above, otherwise pick the category under which this new category will belong. You may optionally specify the sorting order (from lowest to highest) using any integer number. The default sort order for all categories is 0 unless specified otherwise.
After you have entered your data, click on "Add New Category" and your new category will be in the list.
To modify or update categories in AWPCP, scroll past the new category section above and down to the list of existing categories, as shown:
From here, you can do three things:
- Move a category to another place
- Change or update the information about the category (sort order, name)
- Delete the category entirely
To move a category under another category, do the following:
- Select the category you wish to move (using the checkboxes on the left)
- From the drop down above the list that says "Select Move to Category", pick the new parent of this current category
- Click on "Move Selected Categories"
You can move more than one category at a time if you like.
If you wish to make a child category a top level category, look under the Action column and click on the Edit Icon (it looks like a piece of paper) to the right of the category Order column. This will populate the category information at the top of the list, just like you're adding a category for the first time.
Update the information and then click "Save Category Changes".
To delete a category, look under the Action Column and click on the red "Stop" icon to the right of the category Order column. Confirm that you wish to delete it, and then select OK. The category will be deleted.
Admin: Listings
Listings is one of two ways that you can manage ads for AWPCP. The other way is through the Ad Management Panel, which is visible to users but only displays the ads for that particular user.
Listings is a panel that is only visible to the Administrators of your site. It is always active and provides a view of all ads that are present on your site, allowing you to manage them with the following operations:
- Add New Listings
- Edit Ads
- Flag Ads
- Mark Ads as Spam
- Delete Ads
- Approve/Unapprove Ads
- Manage Images
- Search for ads by ID, keyword, title or location
Listings shows the title of the ad, along with a series of links for the various operations, the start date (when the ad was posted) and the end date (when it's set to expire). One link indicates the state of the ad: If you see "Disable", that means the ad is active and visible to your users. If you see "Approve" that means the ad was posted but is awaiting your approval before displaying to the public. The View Images link will also display the count of images associated to the ad. If no images are present on the ad, View Images will be replaced by "No Images" along with an "Add" link to the right of it.
To view an ad, just click on the View link. This will load the ad just like you would see it on the website, in a modified admin form for viewing.
To edit an existing ad, find the title of the ad you wish to edit and click on the Edit link. The Place Ad form will be loaded with all the ad details. When you are done editing, click on "Continue" which will save the information.
If you want to change or update the images, click on Add Image or Manage Images instead of Edit. This will allow you to add, delete or update any image in the ad, within the limits of your payment plan, if any.
IMPORTANT: Most WordPress installations have a default image size limit of 2MB on many web hosting services. If you attempt to upload a file greater than this size, you may encounter errors. These are not the result of a bug in AWPCP, but rather, the limit imposed by WordPress media uploader. You can change this in your WordPress installation manually. Refer to this WordPress forum link for more details.
To remove your ad from the system, simply click on the Delete link. You will be asked to confirm whether you wish to delete the ad or not.
There are two bulk operations you can perform with ads: Delete and Mark as SPAM. To do either of these, check all of the ads you wish to work with using the checkboxes on the right (or use the checkbox at the very top to select/deselect ALL of the ads on the page), and the click the button you wish.
To handle Flagged Ads, you must click the Flagged Ads link at the top of the Listings, just to the right of the search text box. This will filter out all but the flagged ads on your site. When an ad is flagged, it is still visible to the public, but marked for your convenience so you can review it. This prevents abuse by others who may aggressively flag ads they simply don't like or that represent competitors, allowing you to make the choice whether to keep the ad or remove the ad.
Listings also allows you to display ads in paged fashion so you can walk through large amounts of ads quickly. By default, the number of ads displayed per page is 10. But you can increase this up to 100 by 10s (10, 20, 30, etc). This helps you mark large blocks of spam ads quickly if you run into a spammer that is bugging your site.
Admin: Import
This screen controls importing listings via a CSV file.
CSV file format
The CSV Importer accepts CSV files using , (comma) as field delimiter, " (double quotes) for enclosure and \ (backslash) as the escape character.
Using the Import Ad form
To import listings via CSV, you must do the following:
- Provide a CSV file that is of the correct format. Check out the sample CSV and image ZIPs below, with the correct column names you can start with.
- If you want to import images within your listings as well, you must provide a separate ZIP file with all the images contained in it. The names of these images should be referenced in the
imagescolumn of your CSV file. If you have multiple images for a single listing, you must separate them with the Image Separator character:;(semi-colon by default). For example:image1.png;image2.gif;image3.jpg. Set the path to this file in the Zip containing images file form field. - If you did not specify a start date or end date for your listings, you can use a default one under this panel. Set the start date and end date fields accordingly. If you have the
start_dateandend_datecolumns populated in the CSV file, these values will be ignored. - Specify the date format used in the CSV file. There are 2 types and 2 formats:Date Types
- Date only.
- Date with timestamp.
Date Formats
- US.
- European/UK.
Decide which one is used in your CSV file. You cannot mix formats within the file! All dates must all be the same format.
- Update the separators used to define images, dates and times, depending on your CSV file format. The defaults are shown above.
- Decide how to handle categories for import. AWPCP can do it two ways:
- Auto Create Categories: this option is good for new installations where you have an existing set of categories you want to use.
- Generate error if Category not found: this option is good if you already manually setup your categories and want to make sure the import conforms to your existing structure.
NOTE: AWPCP can only handle single-level category creation on import (top level categories only). So if you want something more complex with children, you might want pre-define your categories and use the second option.
- Imported listings can be assigned to a user by using the
usernamecolumn in the CSV file. The username must match a login name of an existing user in your WordPress site. If you want listings assigned to a particular user on import, you should check Assign to User. Otherwise, leave it unchecked. - If you checked Assign to User, and a listing does not have a
usernamedefined in the CSV file, you can assign it to a default user, such as admin. Select the user you wish to use as the default one. Only valid if you checked Assign to User in Step 7. - Once you configure these options, you can try out your import and see if any errors will be generated by clicking Test Import. If all goes well on the test, you can perform the actual import by clicking Import, which will load the AWPCP tables with the data you configured above.
Accepted column names
This is a list of the default accepted column names.
title(required)details(required)contact_name(required)contact_email(required)category_name(required)contact_phonewebsite_urlcountrystatecitycounty_villageitem_pricestart_dateend_dateusername(required if Assign to User is checked)images
Extra Fields support
If you have Extra Fields Module installed, you can import listings with your extra field data too! Suppose you have a set of extra fields defined for cars: vehicle_make, vehicle_model, and vehicle_year. You can have columns for these in your CSV file as well, as long as you have Extra Fields installed, and these fields are already defined prior to import.
Make sure you use the field name, and not the field label for your Extra Field! If what you’re using has spaces in it, it’s probably the wrong one.
Region Control support
The CSV Importer allows importing information for up to one region. There is no need to use columns with special names; if the name of a region matches the values from country, state, city andcounty_village` columns, the listing will be associated with that region automatically.
Sample files
- Sample Basic CSV file: https://awpcp.com/samples/sample.csv
- Sample Image file to go with CSV: https://awpcp.com/samples/images.zip
Admin: Debug
The Debug screen contains a dump of all your AWPCP settings, minus some sensitive fields (like usernames and passwords) to help the AWPCP support team diagnose your problems more quickly.
If requested by the AWPCP support team, please visit your Debug page and use http://fpaste.org to put that data in a place we can access.
Ad Management
Ad Management is one of two ways that you can manage ads for AWPCP. The other way is through the Listings Panel, which is visible to only Administrators but manages all ads for the site.
IMPORTANT: In order to see Ad Management, you must have "Enable User Ad Management" turned ON under Settings->General in AWPCP. This will also implicitly turn on "Require Registration" under Settings->Ad/Listing settings as well. Users can only access Ad Management from their WordPress profile (/wp-admin)
Ad Management is new to AWPCP 2.0 and allows any registered user on the site to manage all of their ads in one place. A user may do the following from Ad Management panel.
- Place Ad
- View an Ad
- Edit Ads
- Delete Ads
- Renew Ads
- Flagged Ads
- Manage Images
- Search for ads by ID, keyword, title or location
Here is what a user might see when they are logged in and are visiting their WP profile page:
The Ad Management Panel displays the Headline, a set of operations you can perform, the Fee Plan (or blank if the ad is not in any payment plan at all), the start date (when it was posted) and the end date (when it will expire). The status (Enabled or Disabled) is displayed, along with the Payment Status indicating whether the ad payment is complete, pending, error, or simply not applicable.
To place a new ad, simply click on "Place Ad" at the top right. This will load the Place Ad form, pre-populated with the user's profile information (Contact Name, Email Address) in the proper fields.
IMPORTANT: If the user's WP profile contains no information for a user's first or last name, the Contact Name field will appear BLANK and will not be editable, since this information is being pulled from the profile.
To view an ad, just click on the View link. This will load the ad just like you would see it on the website, in a modified admin form for viewing.
To edit an existing ad, find the title of the ad you wish to edit and click on the Edit link. The Place Ad form will be loaded with all the ad details. When you are done editing, click on "Continue" which will save the information.
If you want to change or update the images, click on Add Image or Manage Images instead of Edit. This will allow you to add, delete or update any image in the ad, within the limits of your payment plan, if any.
IMPORTANT: Most WordPress installations have a default image size limit of 2MB on many web hosting services. If you attempt to upload a file greater than this size, you may encounter errors. These are not the result of a bug in AWPCP, but rather, the limit imposed by WordPress media uploader. You can change this in your WordPress installation manually. Refer to this WordPress forum link for more details.
To remove your ad from the system, simply click on the Delete link. You will be asked to confirm whether you wish to delete the ad or not.
You can renew an ad by clicking on the Renew Ad link. This will take you to the Renew Ad screen, where you can either pay for another term of listing (paid board) or simply re-run the ad (free board) if the admin allows.
AWPCP Classifieds Front End
This section describes how the AWPCP pages interact on the front end. When you install AWPCP, it installs a number of WordPress pages when you go to Classified Pages setup under General Settings. These pages control the display and workflow of AWPCP. They are:
You can control what each and every one of these pages is named at any time. They all support multibyte characters as well. They will be referred to in the documentation as the names above for consistency.
All of the above pages live under the AWPCP Main page (by default named Classifieds). This main page has the shortcode [AWPCPCLASSIFIEDSUI]. You can place this shortcode in any page on your site to make AWPCP appear in that page.
For example, if you want to make AWPCP the main page on your website's home page, simply set a static page as your home page for WordPress, and then place the shortcode above into that page. AWPCP will automatically appear on it after saving it.
The main display page can run in one of two modes--category mode or "all ads" mode. Category mode shows all of your categories (parents and children), along with an optional count of ads present in them identical to the View Categories page. Ad mode shows the same view as Browse Ads--all ads present sorted by whatever you set under Ad/Listing Settings. You can change category mode vs. ad mode under General Settings, "Show Categories on main page".
IMPORTANT: All of these pages are required by AWPCP to perform various functions of a classified site. Deleting any of them is very bad. Some themes will automatically display ALL pages in your site on a menu, and this may be undesirable. Some AWPCP pages are not meant to be accessed out of context (for example, Reply To Ad can't be viewed without knowing what ad you're replying to. Same with Renew Ad, Show Ad, and many others).
If you see pages displaying that should not be, adjust your theme's menu functions or use the WordPress 3.0 menu editor (if your theme supports it) to hide these pages. Most of the time, you'll want to display these pages:
- Place Ad
- Search Ads
- Browse Ads
- Browse Categories
- View Categories
The rest can be safely hidden away, but not deleted or made private which prevents AWPCP from using them as needed.
Place Ad
Place Ad is the primary page where you enter all the data for your classified ad. Place Ad can be accessed from the front end via the Place Ad link, or from the back end via Place Ad button in the Ad Management Panel or Listings panel.
The Place Ad page uses the short code [AWPCPPLACEAD].
Place Ad may take you through as many as 4 steps to place an ad, depending on what your image and payment settings are. These steps and settings are outlined here:
| Workflow Step | Paid or Free Mode | Setting to Activate |
| Select Category/Pick Payment Plan | Paid mode only | Payment Settings (Enable paid mode) |
| Payment Confirmation | Paid mode only | Payment Settings (Enable paid mode) |
| Enter Details | Both | n/a (always present) |
| Upload Images | Both | Free mode: Image Settings (Number of images allowed, 1 or more) Paid mode: The image count from the Fee Plan |
If you have fee plans with 0 image count OR if you do not allow images on free boards, you will not see the Upload Images step at all.
The Place Ad appears like this on your site when you click the link, after you get past the payment steps (front end view):
And like this when you access it from the Ad Management or Listings panel, also after the payment steps:
The fields that are always required:
- Ad Title (prepopulated when you have Require Registration turned on in Registration Settings, as shown above)
- Contact Name (also prepopulated when Require Registration is on)
- Contact Person's Email
- Description
The other fields may be required depending on what you set for Form Fields options.
Edit Ad
Edit Ad is very much like Place Ad, except that instead of entering all data from scratch, you will have the Enter Details form pre-populated with all of the current ad data.
The Edit Ad page uses the short code [AWPCPEDITAD]. The same restrictions on required fields you have with Place Ad are also present on Edit Ad as well.
When you Edit Ad, you follow the same workflow as Place Ad, but without the payment steps. So in order to change any images, you must save your ad details first, and then move to the second step of managing images.
Browse Ads
Browse Ads is the page used to walk a paginated list of all ads that exist on your classifieds site. The page size is defined inside your Ad/Listing Settings.
The Browse Ads page uses the short code [AWPCPBROWSEADS].
The Browse Ads page looks like this when you select the Browse Ads link from the front end of your site:
Browse Categories
Browse Categories is the page used to walk a paginated list of category-filtered ads that exist on your classifieds site. The page size is defined inside your Ad/Listing Settings.
The Browse Categories page uses the short code [AWPCPBROWSECATS].
The Browse Categories page looks like this when you select a category and click Select Category from the Browse Ads page of your site:
View Categories
View Categories shows all of your categories (parents and children), along with an optional count of ads present in them.
The View Categories page does not use any short code, nor will you find it under WordPress' Pages admin. This is normal--it is dynamically generated by AWPCP.
The View Categories page is shown below:
Search Ads
AWPCP supports the notion of searching for ads based on various criteria. This is done through the Search Ads page, where the standard search fields are present:
You can control which fields are visible in search under Form Fields settings. Also, if you have the Extra Fields module installed, you can display search fields for your extra fields defined in ads. For example, you might have a Make, Model and Year field added for a Car classifieds site. AWPCP Extra Fields would allow you to automatically expose these fields on your Search Ads page so that people can view ads based on those fields.
Clicking on Start Search will take you to the Browse Ads page, filtered for the results you asked for in Search Ads.
Renew Ad
AWPCP supports the notion of renewing an ad just prior to its expiration. Ad Renewal takes place in two places:
- Inside the Ad Management Panel by clicking "Renew Ad" link
- Clicking the link in the email generated by AWPCP when an ad is up for renewal, which takes you to the Renew Ad page externally, populated with the ad data for the relevant expiring ad.
Both processes are similar, so we'll show you the steps from the Ad Management Panel perspective. Starting from the panel, there is a Renew Ad link visible here:
Clicking it brings you to this page:
Where you can select your payment method (in this case, only PayPal is installed) and continue:
After you submit payment, the ad is renewed for another term under the same payment plan as before.
Payment Thanks
The Payment Thanks page is where your users will end up if they do the following:
- They place a (paid) ad
- They attempt to pay for it via PayPal or similar payment service
- During this process, they complete their payment and get returned to your site
On this page, they will receive a message about their transaction status (paid, in process, etc).
This particular page can't be visited outside of the workflow process for AWPCP. You should not delete this page or make it private from your site, although you can prevent it from being displayed in the menus to avoid confusion from your users.
Payment Cancel
The Payment Cancel page is where your users will end up if they do the following:
- They place a (paid) ad
- They attempt to pay for it via PayPal or similar payment service
- During this process, they cancel their payment and get returned to your site
On this page, they will receive a message that their transaction was not completed.
This particular page can't be visited outside of the workflow process for AWPCP. You should not delete this page or make it private from your site, although you can prevent it from being displayed in the menus to avoid confusion from your users.
Reply To Ad
AWPCP uses a "double blind email system" similar to Craigslist for users and posters to contact each other. They do this through the Reply To Ad form, where the user submits the data they wish to send to the poster, and your WP site sends the email on behalf of the user to the poster.
The Reply To Ad page is used to create the reply form when a user clicks on the "Contact <name>" link inside of an ad, such as this one:
Once clicked, the Reply to Ad form is created with the context of the ad:
This particular page can't be visited outside of the workflow process for AWPCP. You should not delete this page or make it private from your site, although you can prevent it from being displayed in the menus to avoid confusion from your users.
AWPCP Premium Modules
AWPCP is a full-featured free classifieds plugin, but there are lots of additional add-ons that you can use to enhance AWPCP and add special functionality that may be of great importance to your kind of site. Currently, AWPCP offers the following modules:
- Extra Fields
- Category Icons
- Regions Control
- RSS Feeds
- Featured Ads
- Fee Per Category
- Coupons/Discounts
- Subscriptions
The Premium Modules are not required to run the main plugin and are all available for an additional fee. You can purchase both single and multi-site licenses for all modules. More information about purchasing them is available here.
Extra Fields
Extra Fields adds the ability to customize your ad form--by adding any kind of field you wish. Some of the things Extra Fields can do:
- You can add a limited number of fields. (The limit is imposed by MySQL, more info here)
- You can use a number of different controls for input on fields:
- Input text box
- Input text area
- Drop Down List (with a set of exclusive values)
- Checkbox (with a set of values)
- Radio Button (with a set of exclusive value)
- Fields can be validated
- Field must have data
- Field must have valid URL
- Field must have valid email address
- Field must be an integer number
- Field must be a decimal number
- Fields can be configured to display on any of these pages: the Show Ad, Place Ad, Edit Ad and Search Ads forms.
- Fields automatically appear on the Search Form. If a field defines a set of values (like a list of car models, or colors), the list will be pre-populated with all valid values for the field in the search form.
- Fields can be public (visible to everyone) or private (visible to admin, but added by original poster)
- Fields can be hidden on some forms, shown on others (e.g. Show in Ad Detail, Hide on Search and Listing, Show on Search, Detail and Listing, etc)
- Fields can be assigned to categories, so you can have different data showing in different categories making each ad more relevant.
Extra Fields is administrated entirely from the Extra Fields menu of AWPCP Classifieds.
Install as follows:
On your WP admin dashboard, click Plugins->Add New. At the top, click Upload and then find the downloaded ZIP file for the module on your local computer. Click OK to start the upload. Activate the plugin when you're done to complete the process.
NEW: Extra Fields now supports individual field codes to use in the HTML template as of 3.5.1+. See this article here for details: https://awpcp.com/forum/faq/valid-field-codes/#p28893
Category Icons
Category Icons is a premium module where you can have AWPCP display small (16x16) icons next to your category names on your main classifieds page. The output looks like this:
How to install Category Icons
Category Icons module is installed as a WordPress plugin manually.
Install as follows:
On your WP admin dashboard, click Plugins->Add New. At the top, click Upload and then find the downloaded ZIP file for the module on your local computer. Click OK to start the upload. Activate the plugin when you're done to complete the process.
Once installed, you can see it in action: Go to your WP admin dashboard under Classifieds->Manage Categories. You should see a third icon that wasn't there before next to each category in the list under the action tab. Clicking on that icon will open the icons page for you to select an icon for the category.
Category Icons comes with Silk's FabFabFab icon pack (courtesy of Dan Caragea) with hundreds of choices. You can also use your own by substituting your own images under this caticons directory and AWPCP will recognize them accordingly. 16x16 works best, although you can use larger images if you make some HTML adjustments to the layout.
Regions Control
Regions Control allows you to create standard regions, such as cities, states, countries, counties, villages, etc. and present the user with a drop down list for the Place Ad process instead of allowing free form text entry, which is difficult to search on.
Install as follows:
On your WP admin dashboard, click Plugins->Add New. At the top, click Upload and then find the downloaded ZIP file for the module on your local computer. Click OK to start the upload. Activate the plugin when you're done to complete the process.
Furthermore, Regions provides an important ability to filter listings based on selecting a particular region (state, city, whatever) by the user. Listings for a category, search result or the entire classified database will be filtered to that's user's chosen location, making their results relevant.
Configuring Regions
The FAQ has a good document on how to configure regions the right way the first time. Start with this article.
RSS Feeds
RSS Feeds allows you to publish your AWPCP ads into an RSS feed that your users can browse in their favorite RSS reader. It allows them to stay in touch with "active content" on your site and bring them back when something catches their interest.
Install as follows:
On your WP admin dashboard, click Plugins->Add New. At the top, click Upload and then find the downloaded ZIP file for the module on your local computer. Click OK to start the upload. Activate the plugin when you're done to complete the process.
The RSS Feeds allows you some simple configuration items at the bottom of the General Tab after RSS feeds in installed. The options are shown below:
On the front end, RSS feeds is activated by clicking on the RSS feeds icon that shows up above your AWPCP main page menus, highlighted inside the red box below (you won't see the red box on your site):
You can also access the feed manually by entering the URL directly, like http://site.com/<awpcpMainPageName>?a=rss
Featured Ads
Featured Ads allows you to highlight certain ads over others, making them more visible than regular ones. This helps to promote certain kinds of ads, or allow you to provide premium fee plans that give users the choice of having this increased visibility. A featured ad in the system appears like this (default style):
Featured ads will always display at the top of any category, search result, or ad list. The featured ads will also appear in a different color with a different border. The default background is yellow and the default border is green. Both of these can be altered using custom CSS for AWPCP. This is the block of CSS used in the default featured ads module. If you want to change it, use AWPCP Custom CSS instead of changing the included file directly.
.awpcp_featured_ad_wrapper {
border: 2px solid #00cc00 !important;
/* IF you want to insert a backround image, then use the following line of CSS: */
/* Uncomment it, change the image name, then put your image in the featured ads plugin directory */
/* or just uncomment it to use the default light green background color in the default image */
background:url("featured_ads.jpg") repeat scroll 0 0 transparent;
}
Featured Ads requires very little configuration. First, install the plugin:
On your WP admin dashboard, click Plugins->Add New. At the top, click Upload and then find the downloaded ZIP file for the module on your local computer. Click OK to start the upload. Activate the plugin when you're done to complete the process.
After that you also need to update the Single Ad HTML template, as follows:
Find the following in your Single Ad listings HTML:
Change this
<div class="$awpcpdisplayaditems"></div>
to this:
<div class="$awpcpdisplayaditems $isfeaturedclass"></div>
After that, Featured Ads will appear in a different style. Your site may already automatically include that $isfeaturedclass variable, which means you don't have to change it yourself.
Featured Ads will add some small additions to existing admin areas, such as the Fees admin area. With Featured Ads installed, you have a NEW option to set a plan to "Featured Ad Pricing" like so:
When you check "Featured Ad Pricing" on a fee plan, it means that any ad placed under the fee plan will be considered "Featured".
Featured Ads are also compatible with Subscriptions as well. You can offer subscription packages of Featured Ads or Regular Ads when Featured Ads is installed.
Fee Per Category
Fee Per Category allows you to charge different amounts on a per-category basis, adding further flexibility on how users can add content to your site. You can create a free/paid site where certain high-quality categories or high-traffic subjects can generate more revenue for you. If you want to have some paid categories and have others that are completely free, this is the module you need.
Fee Per Category requires that you assign payment plans to certain categories. In addition, you must also define a "default payment plan" that is not assigned to ANY category at all. This plan is typically set at $0.00 to allow users to post for free in any category that wasn't explicitly assigned to other plans.
Once you install Fee Per Category and go to the Fees menu in AWPCP, your payment plans will then have a list of categories in them, like so:
You must go through and assign any categories to payment plans to get things rolling. You may assign multiple plans to a single category, or none at all.
If you fail to define a default plan or assign all categories to plans, you will see a warning like this until you finish:
IMPORTANT: You must define ONE payment plan that is not assigned to ANY category at all. This is the "default" plan. Typically, you set this plan to $0.00 so that your users can post in all other categories. If you don't define this plan, your users will not be able to post ads in any categories that don't have explicit fee plans assigned. You will also see the warning in red above.
Coupons/Discounts
The Coupons module allows you to offer coupon codes to your users when posting ads or subscriptions on your site. This gives you the flexibility to give away free ads to certain users for promotional purposes, or to discount your plans if you want to run a special promotion.
Coupons are defined in the Coupons menu that appears under Classifieds after the module is installed:
Once you click on the menu item, the following screen appears (without anything in it initially):
You turn on coupons by checking the box "Use coupon system" and click "Update". This enables the coupon code box on your Place Ad payment form. After that, you can use coupons. Here are what the coupon fields mean:
- Coupon ID is the unique identifier of the code in the system
- Coupon Code is what you give to your users to enter when placing an ad
- Discount Value is the amount of the discount. It can be a percent or an absolute value. The symbol will tell you wish (% after the value for percent, $ before for absolute value)
- Redemption Limit is the total amount of times this code can be used. If you put 0 in this field, the coupon can be redeemed forever.
- Redemption Count is the number of times to date it has been used
- Expire Date is the date when the coupon code is no longer allowed to be used
- Active tells you whether this coupon code currently works or not. Inactive and expired have the same effect from the user's perspective--the code will not work.
To add a new coupon, click on Add Coupon. Enter the data required from above.
To edit or delete a coupon, move your mouse over the record you wish to edit. You will see the Edit and Delete links appear as you hover. Click on the desired operation.
Once your coupons are in place and active, you should see this on your Place Ads form during the second page of payment:
Entering an active discount code will change the price accordingly when you click Apply Coupon.
Subscriptions
Subscriptions module gives you the ability to offer ad "packages" to your users. Instead of just buying one ad at a time, users can have many ads active at once (depending on how you define their packages). These packaged ads give users more flexibility to place multiple ads at once and have them all running at the same time. They can change these ads and continue to renew them all within the life of a single subscription. This is a great way to engage power users or offer bulk ad placement for high-value users.
Subscriptions is activated by going to the General Tab and scrolling down to the bottom. You MUST check "Allow Ad Subscriptions" to turn on Subscriptions FIRST.
After doing that, two things will happen:
- Require registration and Use Ad Management panel are automatically activated if they weren't already.
- You will now see a Subscription Plans link on the Classifieds menu. You will also see a Subscriptions link on the Ad Management menu as well.
First, let's cover the Subscription Plans link:
Clicking on the link will bring you to the Subscription plans screen, where you can create your first subscription plan:
To add a new plan, click "Add Subscription Plan" in the upper right. Editing or deleting plans requires you to hover over the record you want, where the Edit and Delete links will appear. Editing a subscription shows the following screen:
The fields:
- Name is the display name of the plan shown to the users during payment if they buy a subscription plan instead of a single ad
- Description is internal, only displayed on the admin screen
- Price is the amount for the subscription
- Allowed Ad Count is the number of concurrent ads that can be placed under the subscription at a time. Once the limit is reached, no more ads can be posted, but the user can delete existing ads to post new ones if they like.
- Duration is the length of the subscription, not of the ads themselves. Duration says how long the subscription lasts. As long as the subscription is active, the user may have the Allowed Ad Count number of ads in the system for any duration they wish, up to the limit of the subscription expiration date.
- Featured Ads indicates whether the user's subscription ads show up as Featured Ads when posted. Only works when you have the Featured Ads module installed at the same time as Subscriptions.
As subscriptions are purchased, under Ad Management menu, you can see who purchased what by clicking on the Subscriptions link when you are an admin:
This gives you a listing of the owner of a subscription plan, along with current ad counts for that user/plan. A user can only have ONE subscription plan active at any time. You can manually add this to users using the "Add Subscription" button you see to the upper right, in the image above.
When the non-admin users are logged in, this same Ad Management->Subscriptions link is active for them as well, but will only display their subscription plan information, as well as their listings under the Listings link.
When you are placing an ad, subscriptions modifies the initial payment screen options slightly:
Your users can buy a subscription or just do a one-time ad placement now.
Once a subscription is purchased, the payment steps are skipped and you go straight to entering your ad details, as long as the subscription is active AND the allowed ad count has not been exceeded by the user.
AWPCP BuddyPress Integration
The following is a list of features included with the BuddyPress Listings module from AWPCP:
- There will be a Listings tab in the profile page of each user.The tab includes a counter that shows the number of listings available from the user whose profile is being shown. If the user viewing the website is an administrator or the owner of the profile page being displayed, the counter will show the the number of all (enabled and disabled) listings. If the user is a regular user or not logged in, the counter will show the number of enabled listings.
- When the Listings tab is active, three sub-tabs will appear: All, Enabled and Disabled. Each one of the sub-tabs works as a filter that will show all, enabled or disabled listings, respectively.Administrator's or profile owner version:Other user's version:
- When the Listings tab is active, the profile page will show a list of all the Listings posted by the owner of the profile.
- Each listing in the list will have buttons to View, Edit or Delete the listing (shown in the previous screenshot).
- The View button will send the user to a new page where the listing will be shown. The appearance of the listing will be the same used in the standard Show Ad page.
- The Edit button will send the user to a new page where the listing can be edited. The workflow for this page is the same as in the Edit Ad page, but without the email address/access key authentication.
- The Delete button will trigger ajax actions to delete the listing. The user will be asked to confirm the action. If the operation is successful, the listing will be dynamically removed from the list.
- At the top of the list there will be a Create button that will allow the users to create new listings. The create listing workflow would be the same as in the Place Ad page. User's will be asked for payment, if payments terms are configured.
- There will be a WordPress page associated to the Listings component. That page will show a list of all Listings in the system, similar to the way Activity page shows sitewide activities.Administrators can choose the page that is going to be used to show the sitewide listings, from the BuddyPress settings page:
- When a user edits, deletes or create a new listing, an entry will be added to the Activity Stream.
Other user's version:
Administrators can choose the page that is going to be used to show the sitewide listings, from the BuddyPress settings page:
AWPCP Credit System
AWPCP 3.0 or newer includes a feature that allow Ads and Subscriptions to be paid using credit. Each registered user has now a balance associated to his/her account. The balance starts at zero but users can purchase credit from the Admin Dashboard using regular payment methods or administrators can add (and remove) credit to the user's accounts.
How to enable the Credit System
The Credit System has to be enabled from the Payment Settings. Just check the Enable Credit System checkbox and save the settings.
Please note that Charge Listing Fee has to be checked as well (Pay mode must be enabled) in order to have the Credit System enabled. AWPCP will automatically enable Pay mode for you if you forget to do it :).
The Credit System can also be enabled from the new Credit Plans submenu under Classifieds:
How to setup Credit Plans
If you want your users to be able to add credit to the their accounts, you need to define Credit Plans. A credit plan is what allow users to exchange real money for credits in your website. Each plan is just package that gives to the buyer user, a number of credits for a certain price.
To create credit plans, go to the Credit Plans submenu, under Classifieds menu, and click the Ad Credit Button. Fill in the credit plan details: name, description, credits and price and then click the Add button.
How to setup payment terms
The new Fees admin screen allows administrators to define the price in credits and in money for each registered Fee.
The Subcription Plans admin screen also allows administrators to define a price in credits and a price in money.
How to add credit to user accounts
An administrator can add or remove credit from user's accounts from the Manage Credit section, in the Admin Dashboard. Adding or removing credit from an user account is useful if you want to give a gift to one of your users or if you use offline payment methods, to name a couple of cases.
The Manage Credit section is the standard WP Users table, with an additional column to show each user's balance. To access the section go to the Manage Credit submenu under the Classifieds menu.
Move the pointer over the Account Balance column and you'll see actions to Add Credit and Remove Credit:
Clicking any of the actions will replace that row with a small form to Add or Remove credit from that user. Type the number of credits and click the blue button. The account balance for the selected user will be updated.
How to purchase credit (for regular Users)
Regular users have a new item, Account Balance, in their version of the Admin Dashboard. The Account Balance section will show the current balance and allow users to purchase additional credit plans to increase their balance.
Clicking the Add Credit button will start the checkout process showing a list of available Credit Plans:
The rest of the process continues as any other purchase in AWPCP and in the end, if the payment is successful, the account balance will show the newly acquired credits.
How to Place Ads using credit
In AWPCP 3.0 or newer, users start the Place Ad process choosing a category and a payment term. The Payment Term controls the number of images that can be uploaded, the number of characters allowed in the Ad title and Ad details and the price the user has to pay. When the Credit System is enabled, the price of the payment term is shown both in money and in credits.
When the user selects a category, the list of available payment terms updates itself showing those are suitable for the selected category only. The user then proceeds to select a payment term and a method of payment: credits or money. If the user selects money, the process continues normally and the user has to pay for the Ad using one of the available payment methods (PayPal, 2Checkout, Authorize.net and others).
The user can see the current account balance in the top part of the form.
The user can purchase a credit plan while trying to place an Ad, all in the same transaction. This feature is very useful if the user has no enough credits to pay for the selected payment term. The number of credits in the selected credit plan, if any, added to the number of credits in the users's account, should be equal or greater than the cost of the payment term.
If the user decides to purchase a credit plan in addition to the selected payment term. The user would have to go through the standard payment process and use one of the available payment methods to pay for the credit plan. At the end of process, if payment was successful the number of credits in newly acquired credit plan will be added to his/her account balance, and then, the cost of the payment term will be deducted. After that, the user continues entering the Ad details and uploading images.
How to Create a Customer Payment Gateway with AWPCP
Documentation here pertains to AWPCP 3.3.2 and higher.
Implementation Notes
All payment gateways should extend class AWPCP_PaymentGatewayand implement at least the four methods described below:
process_payment: called when the payment gateway is about to be used in a transaction. This is the method used to render the payment buttons in PayPal or 2Checkout payment gateways, and the Billing Form in PayPal Pro Direct Payment or Authorize.Net.process_payment_notification,process_payment_completedandprocess_payment_canceled: that are called when a notification is received for a transaction associated to the payment gateway, or when the user is redirected to thepayment-completedandpayment-canceledURLs.
Most payment gateways allow developers to specify a notify, return and cancel URL. Those are directly associated with the process_payment_notification, process_payment_completed and process_payment_canceled methods above, respectively.
You can use the following code to generate the URLs mentioned above, for a given transaction,
$payments = awpcp_payments_api();
$notify_url = $payments->get_notify_url($transaction);
$return_url = $payments->get_return_url($transaction);
$cancel_url = $payments->get_cancel_url($transaction);
The plugin will handle those URLs automatically and will take care of calling the right method in each case.
The implementation of the methods varies depending on the kind of integration you are trying to develop.
- Integration by Payment Button (PayPal Standard or 2Checkout)
process_payment: should print the payment button.process_payment_completed: called when the user returns to your website from the payment gateway's website, after having made a payment. The method should validate the information received and try to find out if the payment was successful or not, and update the transaction's payment status. This is how PayPal Standard payment gateway works; seepayment-gateway-paypal-standard.php.process_payment_canceled: called when the user returns to your website after he or she cancelled the payment request. The method should update the payment status of the transaction.process_payment_notification: called every time a notification is received for a transaction that used your payment gateway. Similar to whatprocess_payment_completeddoes, this method has to verify the information received and figure out the new payment status and update the transaction accordingly.
After
process_payment_completedorprocess_payment_canceledhave been called, the plugin continues handling the payment transaction and will let the user post the listing, if the payment was successful, or show him an error, if the payment failed. - Integration by Custom Form (Authorize.Net)
process_payment: should print the billing form, but also takes care of precessing the data entered, contacting the payment gateway's servers and consolidate the payment (update the transaction with a proper payment status).When you are done processing the payment, after you have updated the payment status of the transaction, callreturn awpcp_payments_api()->process_payment_completed($transaction);to let the plugin continue handing the transaction and allow the user to post the listing (if the payment was successful).process_payment_completedandprocess_payment_cancelledare usually implemented without a body (just areturn;line), because the user is never redirected during the payment transaction.- If the payment gateway supports notifications, the
process_payment_notificationmethod should be implemented as described in the Integration by Payment Button case.
Registering a payment gateway
Register an action for the awpcp-register-payment-methods hook. The callback will receive an instance of the Payments_API as its only argument. You should create an instance of your Payment Gateway and pass it to the register_payment_method method. For example:
public function register_payment_methods( $payments ) {
$payments->register_payment_method( new AWPCP_PayPalStandardPaymentGateway );
}
Mark as Sold
This module allows website owners to mark listings as sold. When a listing is marked as sold, a special icon will be shown next to the listing to let visitors know is already sold.
Behavior
When the module is activated, the Edit Ad screen in the frontend shows a Mark as Sold button:
If the listing is already marked as sold, an Undo Mark as Sold button will be shown instead:
An image of a red ribbon, with SOLD written on it, is shown over the thumbnail of listings marked as sold. if the default thumbnail is enabled, the ribbon will be shown even if the listing has no images, like in the example below:
The ribbon is shown in the Single Ad page as well:
Listings can also be marked as sold from the Admin Dashboard, using the Mark as Sold and Undo Mark as Sold actions:
Configuration
The module includes the ability to remove sold items from the system, after N days have passed since the listing was marked. Two new options in Settings > Ad/Listings > Moderation allow administrators to configure whether or not this behaviour should be enabled and when:
AWPCP Ad Campaign Manager
This module allows website owners using AWPCP to monetize their classifieds pages through banner advertisements. These banners can be sold and managed through the admin interface and rotated throughout the AWPCP classifieds section in various locations. It can be used with AdSense, but is intended for use with banner ad sales you do directly.
Sales Representatives (SR)
The Campaign Manager module adds a Sales Representative role that allows regular users to have access to the Campaign Management features of the module, without giving them access to other adminsitrative features.
A Sale Representative has the same capabilities as a Subscriber, except they also can create Campaigns.
Advertisement Positions
The Campaign Manager module enables several advertisement positions, described below:
- Top: Allows administrators and SR to show banners on top of the list of listings and main menu, right after the page title.
- Middle: Allows administrators and SR to show a variable number of banners in the middle of the list of listings. A banner spot will be available after every 5 listings.
- Bottom: Allows administrators and SR to show banners below the list of listings.
- Sidebar One & Two: Allows adminsitrators and SR to show banners in the sidebar adding a special wiget, the Advertisement Placeholder widget. When you add the widget to one of your sidebars, you can choose which advertisement position will be shown:
Then, in the frontend, banners for those positions will appear:
The widget can be added to the sidebar as many times as you want, so the same banner could be shown at the top of the sidebar and at the bottom, for example. You could also show a banner from Sidebar One at the top and different banner from Sidebar Two at the bottom. - Footer: Similiar to the Sidebar One and Sidebar Two positions, the Footer position is available using the Advertisement Placeholder. This positions was created to be inserted in "sidebars" that appear in the footer of a webiste, but it can be used in any sidebar.
Then, in the frontend, banners for those positions will appear:
The widget can be added to the sidebar as many times as you want, so the same banner could be shown at the top of the sidebar and at the bottom, for example. You could also show a banner from Sidebar One at the top and different banner from Sidebar Two at the bottom.Advertisement Positions Dimensions
When the plugin is installed, the Top, Middle, Bottom and Footer positions are configured to accept banners of 650x150px, and the Sidebar One and Sidebar Two positions, to accept banners of 250x150px.
Those dimensiones can be adjusted from the module settings, going to Campaigns > Ad. Positions in the admin dashboard.
Campaigns
In order to decide which banners to show and when, administratros and SR need to create Campaigns. A Campaign is created from the Campaigns > Add New Campaign menu item. At first all the information you need to create a campaign is a start date, an end date and whether the campaign is going to be enabled or disabled. Don't worry if you don't have a value for properties yet; they can be changed later just as easy.
When a you create a Campaign, you are redirected to a special page where you can continue editing the campaign. Now there are more fields available. You can start creating Campaign Sections and defining the Campaign Content.
Campaign Sections
A campaign section defines the category of listings, the page of results and the positions where the campaign is going to be active. If you want a campaign to show the top banner in the first page of results for the listings in the California > Auto/Trucks category, then you will create a Campaign Section like the one below:
There is no limit in the number of campaign sections that you can create, so your campaign can be configured to show banners every where.
As soon as you create the first Campaign Section, the page updates itself showing a new kind of form. With Campaign Sections you define where and when to show banners. The new forms allow you to define the content of the banners for each advertisement position.
Campaign Content
In the example above we created a Campaign Section to show the top banner in the list of listings that belong to the California > Auto/Trucks category. Now, with the Campaign Content forms, you are going to control the actual content of the banner:
The content for a given position can be:
- An image.
- An image with a link that points to an URL of your choice.
- Plain text.
- HTML.
- PHP code (that will be executed everytime the banner is being rendered).
As you add more Campaign Sections targeting other advertisement positions, more Campaign Content forms will become available, allowing you to define the content for each position independently.
Placeholder Campaign
There is a special type of campaign that is used to show banners for positions where other Campaigns are not active. We call it the Placeholder Campaign. It work like this: if none of the defined campaigns have a Campaign Section for the bottom banner, in the first page of listings in the Furniture category, the banner defined for the bottom position in the Placeholder Campaign will be used.
The Placeholder Campaign has no Campaign Sections because, as explained above, it applies for all positions, in any page of results, for listings in all categories.
Additionally, there can only be one Campaign Placeholder per website. You can delete it, create a new one, and edit the content of the advertisement positions, but you cannot create more than Campaign Placeholder. It is also not necessary.
Before you create your Placeholder Campaign, is important that you consider how many results per page do you want to show. This number is important because it controls how many middle positions you will have available per page of results. Remember that a spot for a banner in the middle position will be available after every five listings, so if you are showing 25 listings per page, you will have up to 4 middle advertisement positions, and you will be able to show different content for each.
It is important to think about that number before creating the Placeholder Campaign, because when the campaign is created, it will be pre-loaded with a content form for every possible advertisement position, given the current configuration. If you change the number of listings to show per page, after the Placeholder Campaign has been created, you may end up with less content forms, restricting your ability to change what is being shown in the missing positions.
To change the number of listings to be shown per page, go to Classifieds > Settings > Ad/Listings and look for the Pagination Options setting:
Uncheck all of the pagination options and enter the number of results per page you want as the value for the Default number of Ads per page setting.
It is important to disable all pagination options to prevent users from changing the number of results per page. If they are allowed to change how many results are shown in each page, it would be really hard for you and the plugin to control haw many middle advertisemnt positions are available in the website, because it will all depend on the user preferences.
--
The form to edit a campaign placeholder in a website where up to 3 middle positions are available, looks like the form in the image below:
Restricted Categories
This module allows website owners to configure certain categories as restricted, forcing visitors to accept a disclaimer before being able to see the listings posted in that categories.
Behavior
When a new user visits your website, all listings posted in restricted categories won't be shown in the list of listings, search results or in widgets, unless the visitor is explicitely browsing one of the restricted categories. In that case, as we saw above, the user must accept the user disclaimer before any of the listings is shown.
However, users are not required to accept the disclaimer every time they explore a restricted category. If they accept the disclaimer, their choice will be remembered, and from that moment, the plugin will start showing all listings without restrictions.
Configuration
When the module is installed and active, a new settings section becomes available:
The section shows a list of the existing categories with a checkbox in front of each of them. If the checkbox is checked, the category is marked as restricted or protected.
If a user tries to see listings in a category that is restricted, the plugin will show a User Disclaimer that the user must accept before being granted access to the listings in that category. The content of the disclaimer can be configured from the settings section as well. HTML and Plain Text are supported.
The plugin includes a User Disclaimer that warns the visitors about adult-oriented content and informs them that they must be 18 years of age or older in order to access that section of the website. You can change the disclaimer to fit your specific needs.
This is an example of the User Disclaimer as seen by a visitor of your website:
Additionally, if a user tries to post a listing to a restricted category, a different disclaimer is shown. The user must accept the terms of disclaimer before he or she can continue with the process of posting a listing.
This is an example of the User Disclaimer as seen by a visitor trying to post a listing to a restricted category in your website:
