API:Api-samplerequest

From InClickAdServer

Contents

Documentation Purpose

The API Request Example is designed to assist developers in using the inClick Ad Server API by providing an example of an API Request for data. This API Example includes a PHP based example.

Summary

With the inClick Ad Server API, developers can manage data within the inClick Ad Server regardless of the ad servers location, local or remote. It is through the use of the API that allows developers to integrate the inClick Ad Server with third party services. Developers can also create their own user interfaces around the inClick Ad Server API.

PHP Based API Service Request

For the purpose of simplifying this example, we'll utilize the inClick Ad Server API and PHPOlait RPC package that is included with every ad server deployment. This API Request example will reside within a directory of your inClick Ad Server deployment. The example below will create a campaign in the house advertiser account.

  1. Setup your inClick Account
    Setup your inClick.net Account
    Before attempting to use the API Service, you must make sure your inClick.net account has the API Service active. To determine if your account has the API Service active, log into your account and view the Account Summary box.
  2. Create an API Service Key - An API Service Key is an authentication token, a type of password, that authenticates the API Service Request being made. The API Service Key is a value that you arbitrarily create. It is recommended that you create a service key that is not trivial. Need help creating a secure key? Try using a Password Generator Tool.
    • Once you have created an API Service Key, you will need update your inClick Ad Server to allow this key to be used. Open the /globals/globals_custom.php file and add the following lines before the closing PHP tag: 
      <?php
      .....
      $action_vars['api_service_keys'] = array('YOUR_API_SERVICE_KEY');
      define('PHPOLAIT_DIR', INCLICK_BASE_DIR . '/phpolait');
      ?>
      Replace the value of YOUR_API_SERVICE_KEY with the key you created earlier.
  3. From the ad server root directory, create a directory named "api_test". This will be come the working folder for this example.
  4. Inside the api_test folder, create a file called create_campaign.php with the following lines of code: 
    <?php
    require "../globals/globals.php";
    require_once (INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_CampaignManagerClient.php");
    require_once (INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_Campaign.php");
     
    //THE BASE URL OF YOUR AD SERVER DEPLOYMENT
    $base_url = INCLICK_WEB_URL;
    //THE SERVICE KEY TO ACCESS THE API
    $service_key = "YOUR_API_SERVICE_KEY";
    //THE ADVERTISER ID WE WILL BE WORKING WITH
    $user_id = '1001';
     
    //INSTANTIATE THE API CLIENT
    $campaign_manager = new IMG_CampaignManagerClient($user_id, $base_url, $service_key);
    $campaign = new IMG_Campaign();
     
    //SET THE CAMPAIGN DATA OBJECTS
    $campaign->setName("API Test Campaign Name");
    $campaign->setHeadline("API Created Headline");
    $campaign->setDescriptionLine1("Description Line 1");
    $campaign->setDescriptionLine2("Line 2 Description!");
    $campaign->setDisplayURL("www.inclick.net");
    $campaign->setURL("http://www.inclick.net");
    $campaign->addCountryCode("US");
    $campaign->addCountryCode("CA");
    $campaign->addChannelID("2");
    $campaign->addChannelID("3");
    $campaign->addKeywordFromString("broad match word");
    $campaign->addKeywordFromString("[exact match word]");
    $campaign->addKeywordFromString("\"phrase match\"");
    $campaign->addKeywordFromString("-negative match");
    $campaign->setDailyBudget("99.00");
    $campaign->setMaximumCPC("0.50");
    $campaign->setEndDate( mktime(0, 0, 0, date("m"), date("d") + 30, date("Y")) );
    $campaign->setStartDate( mktime(0, 0, 0, date("m"), date("d"), date("Y")) );
    $campaign->setTypeCode( 'cpc' );
     
    //SEND THE REQUEST TO THE API
    $result = $campaign_manager->createCampaign($campaign);
    if($result->getErrorCode())
    {
    echo "Error Code: " . $result->getErrorCode() . "<br>";
    echo "Error Message: " . $result->getErrorMessage() . "<br>";
    }
    else
    {
    echo "Successfully created Campaign ID " . $result->getReturnValue() . "! Log into the House Advertiser account (1001) to see this campaign.";
     
    }
    ?>

Breaking Down the Sample Request

require "../globals/globals.php";

This require references the local inClick Ad Server deployment configuration files allowing your code to utilize the pre-packaged API Objects as well as the bundled PHPOlait services. 

require_once (INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_CampaignManagerClient.php");
require_once (INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_Campaign.php");

These requires (includes) contain the API Objects and Classes needed for this API Service Request. 

$base_url = INCLICK_WEB_URL;
$service_key = "YOUR_API_SERVICE_KEY";
$user_id = '1001';

The $base_url is the URL to your inClick Ad Server deployment, the ad server root URL. For local host API usage, the constant of INCLICK_WEB_URL is defined in the globals.php file referenced earlier. Remote deployments, deployments where the ad server and API Request Location are not on the same server, would change this to the fully qualified URL to the ad server root directory.

The $service_key is one of the API Service Keys you have created.

The $user_id is the inClick Advertiser account number we will be working with for this API Service Request. For this example, we are working with the House Advertiser account, 1001. 

$campaign_manager = new IMG_CampaignManagerClient($user_id, $base_url, $service_key);
$campaign = new IMG_Campaign();

This is where we create an instance of the classes needed to create a new campaign. 

$campaign->setName("API Test Campaign Name");
$campaign->setHeadline("API Created Headline");
$campaign->setDescriptionLine1("Description Line 1");
$campaign->setDescriptionLine2("Line 2 Description!");
$campaign->setDisplayURL("www.inclick.net");
$campaign->setURL("http://www.inclick.net");

Similar to the standard advertisement creation and edit work flow found in the user interface, each $campaign->SetXXXX is assigned its corresponding value. 

$campaign->addCountryCode("US");
$campaign->addCountryCode("CA");
$campaign->addChannelID("2");
$campaign->addChannelID("3");
$campaign->addKeywordFromString("broad match word");
$campaign->addKeywordFromString("[exact match word]");
$campaign->addKeywordFromString("\"phrase match\"");
$campaign->addKeywordFromString("-negative match");

The $campaign->addXXXX objects allow you to add multiple values as needed. In the example, the campaign we are creating will be targeted to two countries, United States of America (US) and Canada (CA) values assigned as the [ISO-3166] Country Code. 

$campaign->setDailyBudget("99.00");
$campaign->setMaximumCPC("0.50");

The $campaign->setDailyBudget and $campaign->setMaximumCPC objects are just as they are described, the daily budget and the max cost-per-click values. 

$campaign->setEndDate( mktime(0, 0, 0, date("m"), date("d") + 30, date("Y")) );
$campaign->setStartDate( mktime(0, 0, 0, date("m"), date("d"), date("Y")) );

The $campaign->setEndDate and $campaign->setStartDate objects are just as they are described, the starting and ending date for the campaign. If these values are not set, the ad server will assume the start date of today and and end date ten years from today.

SHOW STOPPER: Please make sure and use an integer timestamp (seconds since 1970) and not a string value. 
$campaign->setTypeCode( 'cpc' );

The $campaign->setTypeCode defines the campaign type. Only cost-per-click is currently supported at this time. 

$result = $campaign_manager->createCampaign($campaign);

This line is the API Service Reqeust that sends the campaign data to your inClick Ad Server deployment. If a failure occurs, the error code and corresponding error message are returned as objects:

$result->getErrorCode()
$result->getErrorMessage()

If this request is successful, the Campaign ID assigned is available in the following object:

$result->getReturnValue() 
if($result->getErrorCode())
{
echo "Error Code: " . $result->getErrorCode() . "<br>";
echo "Error Message: " . $result->getErrorMessage() . "<br>";
}
else
{
echo "Successfully created Campaign ID " . $result->getReturnValue() . "! Log into the House Advertiser account (1001) to see this campaign.";
 
}

This section of code is provided to give you a visual confirmation of what occurred.

Retrieved from "http://docs.inclick.net/index.php/API:Api-samplerequest"