devisd/advertiseworld-php

This package is abandoned and no longer maintained. No replacement package was suggested.

This libarary allows you to integrate Advertise Worlds Ads into your App, and prevent Ad Blockers from blocking the Ads.

Maintainers

Details

github.com/devisd/advertiseworld-php

Homepage

Source

Issues

Installs: 539

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 6

Forks: 0

Open Issues: 0

1.3.1 2016-12-16 06:44 UTC

Requires

MIT cfacc416b6c42169c865761e58316a357261120c

  • Devisd Pty Ltd <other.woop@devisd.com>

Advertise World AdServing Devisd

This package is not auto-updated.

Last update: 2018-09-29 21:32:45 UTC

README

Total Downloads

A PHP library for serving Ad's from Advertise World

Installation

First you'll need to connect to your server using SSH or Putty or something similar.

Installing Composer

If you haven't installed composer yet, you can install composer locally using the following commands:

cd /<my website root foler>/
wget https://getcomposer.org/composer.phar

If you have root access on your server you can make composer globally available (most developers do this):

chmod a+x composer.phar
mv composer.phar /usr/bin/composer

Installing Advertise World Package Using Composer

If you have just installed composer locally type:

php composer.phar require devisd/advertiseworld-php

If you have made composer globally accessible you can use the following:

$ composer require devisd/advertiseworld-php

or add the following to your composer.json file:

{
    "require": {
        "devisd/advertiseworld-php": "^1.0"
    }
}

If you need to update the library your can just type:

composer update

Requirements

  • PHP 5.3+ with php-curl installed

  • If you use a Server Proxy it must pass all request headers.

Dependencies

  • php-curl
  • fire015/flintstone (composer will automatically download this)

Usage

Simple fix sized ads

This is an example of how to place a fix sized ad on your page using this library. This ad cannot be blocked by ad blockers.

<html>
<head><title>Testing</title></head>
<body>
	<h1>Homepage</h1>

	<p style="border: 1px solid black;">
		<?php
		require_once __DIR__ . '/vendor/autoload.php';
		$ad = new \Devisd\AdvertiseWorld\Ad(__DIR__ . "/ad_db", __DIR__ . "/images", "/images");
		echo $ad->getAd('ffffffff-ffff-ff01-5678-27810b00001c', 'inline', false, false, false, false, 728, 90);
		?>
	</p>
</body>
</html>

Responsive Ad

Response ads will automatically decide which image size to use based on the width of the ads parent HTML element. If the user resizes their browser window, the image will automatically change to reflect the new width of the ads parent HTML element. If there are two or more image sizes available for a given width, then you can decide to use the shortest (Default) or the tallest one.

To use responsive ads, the setup is a little more involved. First create an images folder and ad database folder on your webserver somewhere and make sure they are writable by your web server.

Eg,

cd /var/www/<my website>/
mkdir images ad_db
chown www-data images ad_db

To provide responsive ads, we need to create a php script to provide different images for different sizes. You can do this one of two ways. You can use a rewrite rule on your web server to ensure that ads can't be blocked or you can avoid making a rewrite rules however ads could be blocked by ad blocker.

####1) Without rewrite rule

serveImagesWithoutRewrite.php (Create this php file in your document root folder)

<?php
require_once __DIR__ . '/vendor/autoload.php';
$ad = new \Devisd\AdvertiseWorld\Ad(__DIR__ . "/ad_db", __DIR__ . "/images", "/images", false);
$ad->changeImage();
?>

Placing the ad:

<?php
require_once __DIR__ . '/vendor/autoload.php';
$ad = new \Devisd\AdvertiseWorld\Ad(__DIR__ . "/ad_db", __DIR__ . "/images", "/images", false);
echo $ad->getAd('ffffffff-ffff-ff01-5678-27810b00001c', 'inline', true, "/serveImagesWithoutRewrite.php", false);
?>

####2) With a rewrite rule Unblockable Unblckable Text

serveImagesWithRewrite.php (Create this php file in your document root folder)

<?php
require_once __DIR__ . '/vendor/autoload.php';
$ad = new \Devisd\AdvertiseWorld\Ad(__DIR__ . "/ad_db", __DIR__ . "/images", "/images", false);
$ad->changeImage();
?>

Add Rewrite Rule:

####Apache: Add the following to your .htaccess file

RewriteEngine   On    # Turn on the rewriting engine
RewriteCond     %{REQUEST_METHOD} POST
RewriteRule     ^images/[^/]+$    serveImagesWithRewrite.php    [NC,L]

Or add the following to your httpd.conf

<Directory "/var/www/myapp">
    RewriteEngine   On    # Turn on the rewriting engine
    RewriteCond     %{REQUEST_METHOD} POST
    RewriteRule     ^images/[^/]+$    serveImagesWithRewrite.php    [NC,L]
</Directory>

####Nginx

Add the following to your nginx.conf file

server {
    location  /images {
        if ($request_method = POST) {
            rewrite ^ /serveImagesWithRewrite.php last;
        }
    }
}

####IIS

NOTE: This is untested. Email support@advertiseworld.com before setting this up.

<rule name="AdworldResponsive" stopProcessing="true">
    <match url="/images/.*" />
    <conditions>
        <add input="{REQUEST_METHOD}" matchType="Pattern" pattern="POST" ignoreCase="true" />
    </conditions>
    <action type="Rewrite" url="/serveImagesWithRewrite.php">
</rule>

####Other Webservers

If you use a web server which is not Apache, Nginx or IIS. Then email support@advertiseworld.com and we will help you setup a rewrite rule.

####Placing the response ad on your page Now you can use the library to add unblockable response ads to your web page.

index.html

<html>
<head><title>Testing</title></head>
<body>
	<h1>Homepage</h1>

	<p style="width: 75%; border: 1px solid black; text-align: center;">
		<?php
		require_once __DIR__ . '/vendor/autoload.php';
		$ad = new \Devisd\AdvertiseWorld\Ad(__DIR__ . "/ad_db", __DIR__ . "/images", "/images", false);
		echo $ad->getAd('ffffffff-ffff-ff01-5678-27810b00001c','inline',true,"/images/",true);
		?>
	</p>
</body>
</html>

Reference

Ad::__constructor ($dbDir, $localImgFolder, $imageBaseUri, $checkAndCreateDirectories)

This constructs an Ad instance. This object is then used to place adverts on you web page using the Ad::getAd() function.

Example usage:

$ad = new \Devisd\AdvertiseWorld\Ad(__DIR__ . "/ad_db", __DIR__ . "/images", "/images");
Parameter Required Type Default Value Description
$dbDir Required string 'adworlds_db' This is the path on the server's file system to a folder used to created a database to remember which ad images have downloaded
$localImgFolder Required string 'images' This is the path of the server's file system to the folder used to download the ad images and serve them. This folder can be a shared images folder which is recommended to prevent Ad Blockers, but note that Advertise World will download ad images to this folder. Note: your existing images won't be overwritten (the php function tempnam() is used to generate a unique filename).
$imageBaseUri Required string no default This is the URI for the image folder, Eg, if the $localImgFolder is accessed via http://mysite.com/images/, then this parameter would be '/images/'
$checkAndCreateDirectories Optional boolean true If TRUE then we'll attempt to create the directories for $dbDir and $localImgFolder if they don't exist. Setting this to false is highly recommended.

Ad::getAd ($adSpaceId, $displayStyle, $responsive, $changeImageScript, $usingRewrite, $tallestAd, $width, $height, $timeout_override)

This function returns a string of HTML code that can used to place an ad on your web page.

Examples:

// Fixed size ad
echo $ad->getAd('ffffffff-ffff-ff01-5678-27810b00001c', 'inline', false, false, false, false, 728, 90);
// Response ad without the web server rewrite rule in place 
echo $ad->getAd('ffffffff-ffff-ff01-56ba-8afe97000001', 'inline', true, "/serveImagesWithoutRewrite.php", false);
// Response ad with the web server rewrite rule in place
echo $ad->getAd('ffffffff-ffff-ff01-56ba-8afe97000001', 'inline', true, "/images/", true);
Parameter Required Type Default Value Description
$adSpaceId Required string no default This is the unique Ad Space Id for the ad area on your page. You can retrieve the Ad Space Id by logging into the Advertise World Portal and clicking the 'HTML Code' button next to the Ad Space.
$displayStyle Optional string 'inline' This is the CSS display style that should be applied to the Ad. This option will generally be 'inline', 'block', or 'inline-block' but you can specify any CSS display style.
$responsive Optional boolean true This turns on responsive ads. The most appropriate ad size will automatically be chosen for the browser based on the width of the ads parent HTML element.
$changeImageScript Required if $responsive=true boolean no default This is the URL for your serveImage.php script. The URL can be relative or absolute. We recommend using absolute path if you can. This URL is required to be working when the ad image changes otherwise the user will see a broken image symbol.
$usingRewrite Optional boolean false This flag indicates if you are using the rewrite method described above to enables image serving of responsive ads. If is recommended to use rewrites and setup this value to TRUE so that ad blockers can't block the ads.
$tallestAd Optional boolean false The responsive ad may have two or more images of the same width. We can decide to use either the shortest image or the tallest image (within the device height). If this is FALSE which is the default, it will automatically select the shortest height image. If TRUE then the tallest image within the devices height is chosen.
$width Optional int false If $responsive is FALSE and you provide a width and height, then your website will always serve an Ad image of the specified width/height. Valid ad dimensions are 120x240, 120x600, 125x125, 160x600, 180x150, 200x200, 234x60, 250x250, 300x250, 300x600, 300x1050, 320x50, 320x100, 336x280, 468x60, 728x90, 970x250, 970x90. If $responsive is TRUE then this parameter is ignored.
$height Optional int false The height on the ad you want to serve. Similar to the $width parameter, if $responsive is TRUE then this parameter is ignored.
$timeout_override Optional int false You can override the server to server communication timeout. The default is 7 which means 7 seconds.

Ad::changeImage ($timeout_override)

This function is used by the PHP script that provides responsive images. The function will respond with the binary data for the new image and handle caching of the image.

Example PHP script to provide responsive images (serveImagesWithoutRewrite.php or serveImagesWithRewrite.php)

<?php
// Including composer's autoload script is needed so that the fire015/flintstone package is available
require_once __DIR__ . '/vendor/autoload.php';

$ad = new \Devisd\AdvertiseWorld\Ad(__DIR__ . "/ad_db", __DIR__ . "/images", "/images");
$ad->changeImage();
?>
Parameter Required Type Default Value Description
$timeout_override Optional int false You can override the server to server communication timeout. The default is 7 which means 7 seconds.

##Proxies On Your Server

If your server uses a proxy to serve your website then the proxy must pass on all request headers.

Using Nginx to provide load balancing is a common example of a server proxy. You can ask Nginx to pass all request headers by adding the following lines to your nginx.conf file:

proxy_pass_request_headers      on;
proxy_set_header                X-Real-IP           $remote_addr;
proxy_set_header                X-Forwarded-For     $proxy_add_x_forwarded_for;