Difference between revisions of "How to Configure a Web Ad Manager Server"

Revision as of 08:52, 5 March 2014

Summary

Web Ad Manager consists of the following parts:

• the Ad Manager desktop application components: these include the ActiveX components which expose the Ad Manager data and business logic to the web application;
• the Ad Manager Web Host service: it provides the context in which the web application loads the Ad Manager ActiveX components;
• the Apache HTTP Server with a PHP preprocessor: it makes the web application accessible on the Internet;
• the web application files: the HTML, CSS, Javascript, PHP and other files which make up the web application.

To configure a Web Ad Manager server we need to make sure all of these elements are installed and configured.

Install Ad Manager

◊ Install Ad Manager (including any add-ins) as if you're setting up another client workstation.

◊ You will also need to create a Role in Ad Manager called "Ad Manager Web User". Any users that need to access the data must be assigned to this role.

Install and configure the Ad Manager Web Host service

The Ad Manager Web Host service provides a process context in which the web application will load Ad Manager's business logic ActiveX components.

Set up a user account for the Web Host service

The Web Host service needs to run as a user who:

• can run Ad Manager if logged on interactively;
• belongs to the local machine's Administrators group.

Ideally, you'll designate a user account specifically for the Web Host service. It can be a local machine or a domain account.

Steps

◊ Pick or create a user account.

◊ Make sure the account belongs to the local Administrators group.

◊ Log on as the user, run Ad Manager and import the Ad Manager serial number and license into the user profile.

◊ If you're using Windows authentication to access the Ad Manager databases in SQL Server, grant the user account access to all database that will be exposed through the web application.

Install and register the Web Host service

The Web Host is an out-of-process ActiveX server packaged as a Windows service.

Its installer will place the executable on the drive but it will not register it as a service; you'll need to do that manually.

When the service is registered, it will be configured to run as the Local System account; you'll need to change that manually.

There's no need to change the service startup type from Manual to Automatic - the service will be started when needed.

Steps to Install

◊ Run the Ad Manager Web Host installer (Amwh.msi).

◊ Install the program for Everyone, not Just me.

◊ Register the service: select the Register Service shortcut in Start -> All Programs -> Dot2Dot Ad Manager Web Host.

◊ Configure the Ad Manager Web Host service to run as the designated user:

• Open the Services management console;
• Right-click on the "Dot2Dot Ad Manager Web Host Service" and select Properties;
• Go to the Log On tab;
• Select This account in the Log on as options;
• Enter the account name in the form domain\user if it's a domain account or .\user if it's a local machine account;
• Enter and confirm the password;
• Click OK.

Steps to Remove an Older Version

◊ Stop the Apache web service.

◊ Unregister the Web Host service: select the Unregister Service shortcut in Start -> All Programs -> Dot2Dot Ad Manager Web Host.

◊ Uninstall Dot2Dot Ad Manager Web Host from the Programs control panel.

Configure the database connections for the Web Host service

The web application can expose the data in one or more Ad Manager databases. The Web Host service needs to know how to connect to those databases.

Each database connection is identified by a unique name. When sharing Ad Manager items online, the connection name will be part of the generated URL. If there's only one Ad Manager database you can leave the connection name blank.

Steps

◊ Run the Ad Manager Web Host configuration utility: select the Configure shortcut in Start -> All Programs -> Dot2Dot Ad Manager Web Host.

◊ Go to the Ad Manager Connections tab.

◊ Add an entry for each Ad Manager database that will be accessible through the web application:

• click the New button;
• enter a unique name for the connection;
• enter the SQL Server name or IP address;
• enter the SQL Server database name;
• enter the SQL Server user id and password; if those are left blank, the Web Host service will use Windows authentication to connect to SQL Server;
• click Test... to verify the connection;
• click OK to save the connection.

◊ Click Apply to save the changes or OK to save the changes and close the configuration utility.

Install and configure the Apache HTTP Server and the PHP preprocessor

The web application requires an Apache HTTP Server (2.4.x or later) with a PHP preprocessor (5.4.x or later).

Although it's possible to download and install Apache and PHP individually, we use a distribution called WampServer which bundles Apache and PHP (plus MySQL, which is not required by Ad Manager) along with some convenient configuration and administration tools.

Install WampServer

Steps

◊ Go to the WampServer download page.

◊ Locate the following download: WAMPSERVER (32 BITS & PHP 5.4) 2.4. Note: the 64-bit version doesn't seem to include the COM/.NET extension for PHP.

◊ Click the download button; you'll get a message which contains the following:

• a link to the WampServer download;
• a warning that WampServer requires the Microsoft Visual C++ 2010 SP1 Redistributable Package;
• links to the 32-bit and the 64-bit installers of that package.

◊ Open the WampServer download link in a new tab and let the browser download the WampServer installer. (Warning: it's a SourceForge download - tread carefully).

◊ Open the appropriate Visual C++ link and download the installer. Alternatively, you can use these links:

• Microsoft Visual C++ 2010 SP1 Redistributable Package (x86)
• Microsoft Visual C++ 2010 SP1 Redistributable Package (x64)

◊ Run the Microsoft Visual C++ 2010 SP1 Redistributable Package installer.

◊ Run the WampServer installer. The default installation folder is C:\wamp; you can change that, but don't bury it too deep so the web application file paths don't get too long.

◊ Run WampServer. A green W icon should appear in the taskbar notification area ("tray").

Configure Apache

Steps

◊ Verify that port 80 is not used by another service:

• Click the WampServer tray icon and select Apache -> Service -> Test Port 80;
• You should see the following message (in a command prompt window):

Your port 80 is actually used by :
Server: Apache/2.4.4 (Win32) PHP/5.4.16
Press Enter to exit...

• If port 80 is used by another service you'll have to resolve the conflict.

◊ Allow access to the Apache server from IP addresses other than localhost:

• Open the Apache config file (httpd.conf): click the WampServer tray icon and select Apache -> httpd.conf;
• Locate the following text:

#   onlineoffline tag - don't remove
     Order Deny,Allow
     Deny from all
     Allow from 127.0.0.1
     Allow from ::1
     Allow from localhost

• Change it to:

#    onlineoffline tag - don't remove
     Order Allow,Deny
     Allow from all

• Save the file
• Restart the Apache service: click the WampServer tray icon and select Apache -> Service -> Restart Service;

◊ Enable the Apache "rewrite" module:

• Click the WampServer tray icon and select Apache -> Apache Modules;
• Scroll to rewrite_module and make sure it's checked; this will uncomment a line in the httpd.conf file:

LoadModule rewrite_module modules/mod_rewrite.so

◊ Configure the Apache service to start automatically:

• Open the Services management console;
• Right-click on the "wampapache" service and select Properties;
• In the General tab set the Startup type to Automatic;
• Click OK.

Configure PHP

Steps

◊ Open the php.ini file: click the WampServer tray icon and select PHP -> php.ini

◊ Enable the COM/.NET extension

• Search the file for the following section and if you don't find it, add it to the bottom of the file:

[COM_DOT_NET] 
extension=php_com_dotnet.dll 

◊ Disable the PHP script execution timeout

• Search the file for the following section:

max_execution_time = 30

• change it to

max_execution_time = 0

◊ If you made changes, save them and restart the Apache service.

Install and configure the Ad Manager web application

Copy the web application into the Apache root directory

The Ad Manager web application consists of a set of HTML, PHP, Javascript and other files. Deploying it is as simple as placing those files in a sub-directory of the Apache root directory ("www"). The name of that directory becomes part of the URL of the web application. For instance, if you name the directory ad-manager, then the application URL will be http://host/ad-manager/ (where host is the web server's DNS name or IP address).

Steps

◊ Decide what to name the application directory (e.g. ad-manager).

◊ Open the Apache root directory: click the WampServer tray icon and select www directory.

◊ Create a sub-directory of the Apache root directory with the name you've chosen.

◊ Extract the contents of the ad-manager.zip file into the newly created directory. Your directory structure should look like this:

- www
  - ad-manager
    + api
    + fonts
    + img
    + js
      ...
      index.html

Configure the Google API Key

The Ad Manager web application uses the Google Maps API.

All applications using the Google Maps API use an API key. Using an API key enables you to monitor the application's Google Maps API usage, and ensures that Google can contact you about your application if necessary. If the application's Google Maps API usage exceeds the Usage Limits, using an API key allows you to purchase additional quota; otherwise the application might stop working.

To obtain a Google API Key you need a Google account.

Steps

◊ Obtain a Google API Key:

• visit the Google Cloud Console and log in with your Google Account;
• go to the Projects tab, click the Create Project button, type a name (e.g. "Web Ad Manager"), and click Create;
• go to the APIs and auth -> Registered apps tab of the project
• click the Register App button, type a name (e.g. "Web App"), select Web Application as the platform, and click Register;
• expand the Browser Key section of the registered app screen and copy the API Key;
• optionally, click the Restrict access button to limit the use of the key to domains you control (e.g. *.mydomain.com/*).

◊ Store the Google API Key in the cfg.json file

• Open the the cfg.json file, located in the js sub-folder of the web app, in a text editor;
• Find this section:

{
  ...
  "google": {
    "maps": ""
  }
  ...
}

• Change it to:

{
  ...
  "google": {
    "maps": "the-api-key-you-obtained-earlier"
  }
  ...
}

• save and close the file.