API Example Create a Campaign

From InClickAdServer

Creating a New Campaign

This API Service Request will create a new campaign for the specified advertiser.

The Code Example

  1. <?php
  2. require "../globals/globals.php";
  3. require_once (INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_CampaignManagerClient.php");
  4. require_once (INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_Campaign.php");
  5.  
  6. //THE BASE URL OF YOUR AD SERVER DEPLOYMENT
  7. $base_url = INCLICK_WEB_URL;  
  8. //THE SERVICE KEY TO ACCESS THE API
  9. $service_key = "YOUR_API_SERVICE_KEY";  
  10. //THE ADVERTISER ID WE WILL BE WORKING WITH
  11. $user_id = '1001';  
  12.  
  13. //INSTANTIATE THE API CLIENT
  14. $campaign_manager = new IMG_CampaignManagerClient($user_id, $base_url, $service_key);
  15. $campaign = new IMG_Campaign();
  16.  
  17. //SET THE CAMPAIGN DATA OBJECTS
  18. $campaign->setName("API Test Campaign Name");
  19. $campaign->setHeadline("API Created Headline");
  20. $campaign->setDescriptionLine1("Description Line 1");
  21. $campaign->setDescriptionLine2("Line 2 Description!");
  22. $campaign->setDisplayURL("www.inclick.net");
  23. $campaign->setURL("http://www.inclick.net");
  24. $campaign->addCountryCode("US");
  25. $campaign->addCountryCode("CA");
  26. $campaign->addChannelID("2");
  27. $campaign->addChannelID("3");
  28. $campaign->addKeywordFromString("broad match word");
  29. $campaign->addKeywordFromString("[exact match word]");
  30. $campaign->addKeywordFromString("\"phrase match\"");
  31. $campaign->addKeywordFromString("-negative match");
  32. $campaign->setDailyBudget("99.00");
  33. $campaign->setMaximumCPC("0.50");
  34. $campaign->setEndDate( mktime(0, 0, 0, date("m"), date("d") + 30, date("Y")) );
  35. $campaign->setStartDate( mktime(0, 0, 0, date("m"), date("d"), date("Y")) );
  36. $campaign->setTypeCode( 'cpc' );
  37.  
  38. //SEND THE REQUEST TO THE API
  39. $result = $campaign_manager->createCampaign($campaign);
  40. if($result->getErrorCode())
  41. {
  42.     echo "Error Code: " . $result->getErrorCode() . "<br>";
  43.     echo "Error Message: " . $result->getErrorMessage() . "<br>";
  44. }
  45. else
  46. {
  47.     echo "Successfully created Campaign ID " . $result->getReturnValue() . "! Log into the House Advertiser account (1001) to see this campaign.";
  48.  
  49. }
  50. ?>

Breaking it Down

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";

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 the api_service_keys values you created for your ad server. (more information) 

$user_id = '1001';  
 
//INSTANTIATE THE API CLIENT
$campaign_manager = new IMG_CampaignManagerClient($user_id, $base_url, $service_key);
$campaign = new IMG_Campaign();

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.

The remaining two lines 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");

These parameters are the various portions of the campaigns creative. Assign each $campaign->SetXXXXX with the corresponding values. 

$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 added multiple values as needed. In this example, the campaign we are creating will be targeted to viewers in two countries, United States of America (US) and Canada (CA). We then set each country as seen in this code snippet. Country codes are based on ISO-3166 standards. 

$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 for this campaign. 

$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.

WARNING: Values for $campaign->setEndDate and $campaign->setStartDate are integer timestamps. Do not enter date formatted values! For example, the timestamp value for May 24, 2023 is 1684900800. 
$campaign->setTypeCode( 'cpc' );

The #campaign->setTypeCode defines the campaign type. Only cost-per-click is 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_Example_Create_a_Campaign"