Utilisation de l'intertace deprog ram mation AdWords deGoogle avec la bibliothèque PHPAPllityThomas Steiner

Niveau de difficulté : o

Pour de nombreux utilisateurs, les recherchessur Google sont devenus incontournablesdans leur travail quotidien sur Internet. Mais,quel util isateur ne s'est jamais demandéd'où pouvaient provenir les petites annoncestextuelles à droite de leur écran ? Le programmed'annonces publicitaires de Google s'appelleAdWords. Sous les quatre lignes de texte toutessimples par annonce en arrière-plan se cache enréalité un système extrêmement dynamique deplusieurs annonces concurrentes en arrière-plan.

e présent article a pour objectif devous présenter I'accès à I'interfacede programmation AdWords de

Google au moyen de la bibliothèque PHPintitulée APllity, elle-même proposée par

Google sous forme de projet open sourcehébergé sur SourceForge. net.

Sur les moteurs de recherche, I'utili-sateur exprime de façon très précise cequ'il souhaite trouver. Prenons I'exempled'un internaute situé à Londres cher-chant à acheter un nouveau vélo. Unerequête de recherche optimale consiste-rait dans ce cas à taper magasin vélosLondres. Supposons maintenant qu'Alice

soit propriétaire d'un magasin de vélosà Londres. Ces deux personnes pour-

raient être mises en contact au moyend'une annonce publicitaire textuelle surGoogle. À chaque fois qu'un internautetape l'expression magasin vélos Londressur un moteur de recherches, I'annoncepublicitaire textuelle d'Alice pourrait alorss'afficher. Ce pourrait également être le

cas sur les mots clés vélos, vélos pas

chers, excursions à vélos Londres oumême magasin v/os (vous aurez remar-qué la faute d'orthographe). Supposonsmaintenant qu'Alice ne soit pas la seulepropriétaire de magasin de vélos. Bob etCameron ont également décidé d'utiliserle Web afin de prospecter de nouveauxclients. Mais, qui décide des textesà afficher en première position des sitesles plus visités ? La réponse à cettequestion fondamentale réside dans unesimple formule :

A d R a n k = C o s t P e r C l i c k * Q u a l i t y S c o r e

Ce qu'il faut savoir...Vous devriez avoir les bases de la pro-grammation orientée objet en PHP5.

Get article explique...Vous apprendrez comment créer une ap-plication simple Google AdWords.

Thomas Steiner (tomac@google.com)travaille pour Google, lnc. en tant qu'in-génieur logiciel. C'esf un feruent partisande l'inteiace de programmation Ad-Words. ll est également chargé du prcietopen source APllity.

www.phpsolmag.org PHP Solutions N" 4/2006

t

Premiers pas avec la b ib l io thèque APl l i tyLa bibliothèque APllity est hébergée en tant que projet open source sur SourceForge.net.Allez sur le site http://google-apility.sourceforge.net, téléchargez la version la plus récente,puis dézippez le package dans un dossier auquel PHP a accès. La bibliothèque est struc-turée comme suit :

Un manuel d'introduction et des références d'instructions se trouvent dans le dossier docLe dossier l ib contient dif férents composants de la bibl iothèque.Le dossier int i tulé wsdl-cache, toujours vide, comprend les f ichiers WSDL requis parla bibl iothèque (nous aborderons ce point plus en détai l ul térieurement).Enfin, le principal dossier, int i tulé APll i ty, comprend quelques f ichiers texte readme,un f ichier zip avec une suite de tests, et plus important encore, deux f ichiers ini et lef ichier api l i ty.php.

ExigencesLa bibliothèque APllity fonctionne à la fois avec PHP4 et PHPS. Afin d'être sûr de fairefonctionner la fonctionnalité de téléchargement de rapports, APllity exige d'activer I'exten-sion CURL, proposée avec PHP. Vous trouverez de plus amples informations sur la procé-dure à suivre à partir du site de PHP (http://vvww.php.neilcurl).

Seuls les utilisateurs de PHP4 auront besoin de I'extension DOM XML proposée avecPHP4 (http://www.php.neildomxml), mais remplacée par DOM sous PHPS et désormaisintégrée au noyau de PHP5. La bibl iothèque APll i ty contrôlera dès son instal lat ion la bon-ne conformité avec ses exigences, et affichera une alerte en cas de problèmes

Paramétrer la bibl iothèqueChaque requête soumise à I'interface de programmation AdWords nécessite une authen-t i f icat ion ainsi que I ' indication d'une marque du développeur censée identi f ier chaquedéveloppeur. Veuillez consulter I'encadré détaillant le processus à suivre pour paramétrerun compte AdWords, puis avoir accès à I'interface de programmation. Nous supposeronsdans cette paftie que vous avez déjà ouvert un compte et possédez toutes les donnéesd'accès complémentaires. Afin de faciliter le processus d'authentification, la bibliothèqueAPll i ty ut i l ise le f ichier central int i tulé authentication.ini.

En règle générale, une agence publici taire possède plusieurs cl ients, chacun d'entreeux ayant accordé à I'interface de programmation de I'agence un accès à leurs comptes.Ces cl ients sont regroupés dans le My Client Center (MCC, ou Mon Centre Client) del'agence. Le gestionnaire du MCC est appelé gestionnaire client. La première adresseemail du gestionnaire cl ient identi f ie I 'agence, alors que la première adresse email de cha-que cl ient du gestionnaire identi f ie le cl ient en question. Ainsi, af in d'avoir accès à un cl ientparticulier, il faut vous identifier avec I'adresse email de votre gestionnaire client, votre motde passe, votre marque développeur et I'adresse email particulière du client. Ouvrez lefichier authentication.ini, et entrez-y une seule fois ces données. Vous êtes enfin prêt.

groupe d'annonces comporte une listede mots clé ou de critères de sites Web,ainsi qu'une l iste de créations (annonces

textuelles apparaissant sur le moteur derecherche). Alice peut choisir le CPC maxi-mum par mot clé qu'elle est prête à payer,

ou plus simplement un CPC par défaut pargroupe d'annonces. Dans le même ordred'idée, chaque mot clé peut avoir sa pro-

pre URL de destination vers laquelle seraacheminé I 'ut i l isateur lorsqu' i l cl iquera surl 'annonce (comme par exemple, chaque

sous-catégorie du fabricant sur le site dumagasin de vélos), ou tout simplementune URL générique (comme par exemple,la principale entrée du site du magasin devélos). De même, les campagnes et lesgroupes d'annonces peuvent être exacte-ment adaptés aux besoins de I'annonceur.Les campagnes, par exemple, peuvent

être ciblées régionalement, les groupes

d'annonces peuvent être suspendus oucomplètement supprimés (lorsqu'Alice

décide, par exemple, de ne plus vendreles vélos d'un certain fabricant). Lesrapports de performance permettent auxannonceurs de suivre les résultats de leurscomptes AdWords.

Interface de program-mation AdWordsAfin de gérer un système aussi com-plexe, Google s'est adapté aux besoinsdes annonceurs en leur proposant uneinterface plus eff icace qu'une simple ap-pl icat ion Web frontale. Google propose

donc une interface de programmationpermettant à une agence publici taire deté lécharger en une seule fo is une quan-

t i té énorme de mots clé, sur laquelletoutes les campagnes d'un annonceurpeuvent être automatiquement suspen-dues en cas d'évènements imprévus,et permettant à I 'entrepôt d'une sociétéd' interagir avec le prix des mots clé cor-respondants. L' interface de programma-

tion de Google permet de nombreusesut i l i sa t ions.

Les annonceurs peuvent choisir le coûtmaximum par cl ic (CPC) qu' i ls sont prêts àpayer, alors que la note de qualité est dé-terminée par le taux de cl ics (cl ickthrough

rate, ou CTR) sur chaque mot clé, la per-

tinence du texte de l'annonce, la perfor-

mance historique des mots clé, et d'autresfacteurs. Le système dépend donc ausside la pertinence des annonces.

Structure d'un compteAdWords GoogleUn compte AdWords Google se composede différentes campagnes. Suivant l'exem-ple précédent, Alice devrait posséder

différentes campagnes pour les VTT et lesvélos de course. Chaque campagne con-tient un ou plusieurs groupes d'annonces.Ainsi, la campagne d'Alice sur les vélos

de course peut comprendre des groupes

d'annonces par fabricant. Enfin, chaque

PHP Solut ions N" 4/2006

Traff icE st imate php

Traff icE st imate php

h

s g

Your Appliætion

Figure 1. Structure des c/asse s de la bibliothèque APllity

Traff lcE st imate php

TraffrcE st imate php

Traff icE st imate php

Traff icE slrmate php

www.phpsolmag.org

Traff icE st imate php

net.nte,r r ta-

turée comme suit :

. Un manuel d'introduction et des références d'instructions se trouvent dans le dossier doc'

. Le dcssier l ib contient dif férents composants de la bibl iothèque.

. Le dossier int i tulé wsdl-cache, toujours vide, comprend les f ichiers WSDL requis par

la bibl iothèque (nous aborderons ce point plus en détai l ul térieurement) '. Enfin, le principal dossier, int i tulé APll i ty, comprend quelques f ichiers texte readme'

un f ichier zrp avec une suite de tests, et plus important encore, deux f ichiers ini et le

f ichier api l i tY PhP.

groupe d'annonces comporte une liste

de mots clé ou de critères de sites Web,

ainsi qu'une liste de créations (annonces

textuelles apparaissant sur le moteur de

recherche). Alice peut choisrr le CPC maxi-

mum par mot clé qu'elle est prête à payer,

ou plus simplement un CPC par défaut par

groupe d'annonces. Dans le même ordre

d'idée, chaque mot clé peut avoir sa pro-

pre URL de destination vers laquelle sera

acheminé I'utilisateur lorsqu'il cliquera sur

I'annonce (comme par exemple, chaque

sous-catégorie du fabricant sur le site du

magasin de vélos), ou tout simplement

une URL générique (comme par exemple,

la principale entrée du site du magasin de

vélos). De même, les campagnes et les

groupes d'annonces peuvent être exacte-

ment adaptés aux besoins de I'annonceur.

Les campagnes, Par exemPle, Peuvent

être ciblées régionalement, les groupes

d'annonces peuvent être suspendus ou

complètement supprimés (lorsqu'Alice

décide, par exemple, de ne plus vendre

les vélos d'un certain fabricant)' Les

rapports de performance permettent aux

annonceurs de suivre les résultats de leurs

comptes AdWords.

Interface de Program-mation AdWordsAfin de gérer un sYstème aussi com-

plexe, Google s'est adapté aux besotns

des annonceurs en leur proposant une

interface plus eff icace qu'une simple ap-

pl icat ion Web frontale. Google propose

donc une interface de programmation

permettant à une agence publici taire de

télécharger en une seule fois une quan-

t i té énorme de mots clé, sur laquelle

toutes les campagnes d'un annonceur

peuvent être automatiquement suspen-

dues en cas d'évènements imPrévus,

et permettant à I'entrepÔt d'une société

d' interagir avec le prix des mots clé cor-

respondants. L' interface de programma-

tion de Google permet de nombreuses

ut i l i sa t ions.

Les annonceurs peuvent choisir le coût

maximum par cl ic (CPC) qu' i ls sont prêts à

payer, alors que la note de qualité est dé-

terminée par le taux de clics (clickthrough

rate, ou CTR) sur chaque mot clé, la per-

tinence du texte de I'annonce, la perfor-

mance historique des mots clé, et d'autres

facteurs. Le système dépend donc aussi

de la pertinence des annonces.

Structure d'un compteAdWords GoogleUn compte AdWords Google se compose

de différentes campagnes. Suivant I'exem-

ple précédent, Alice devrait posséder

différentes campagnes pour les WT et les

vélos de course. Chaque campagne con-

t ient un ou plusieurs groupes d'annonces'

Ainsi, la campagne d'Alice sur les vélos

de course peut comprendre des groupes

d'annonces par fabricant. Enfin, chaque

PHP Solut ions N" 4/2006

Traff icE strmate PhP

Traft icE st imate php

Traff icE strmate PhP

Traff icE st imate PhP

Your Application

Figure 1. Structure des c/asse s de la bibliothèque APllity

www.phpsolmag.org

TraficE st imate phP

IraFfrcE shmate PhP

Traff icE strmate php

Traff icE strmate phP

Premiers pas avec la bibl iothèque APl l i tyLa bibliothèque APllity est hébergée en tant que projet open source sur SourceForge.net.Allez sur le site http://google-apility.sourceforge.net, téléchargez la version la plus récente,puis dézippez le package dans un dossier auquel PHP a accès. La bibliothèque est struc-turée comme suit :

. Un manuel d'introduction et des références d'instructions se trouvent dans le dossier doc.

. Le dossier lib contient différents composants de la bibliothèque.

. Le dossier intitulé wsdl-cache, toujours vide, comprend les fichiers WSDL requis parla bibl iothèque (nous aborderons ce point plus en détai l ul térieurement).

. Enfin, le principal dossier, intitulé APllity, comprend quelques fichiers texte readme,un fichier zip avec une suite de tests, et plus important encore, deux fichiers ini et lef ichier api l i ty.php.

ExigencesLa bibliothèque APllity fonctionne à la fois avec PHP4 et PHPS. Afin d'être sûr de fairefonctionner la fonctionnalité de téléchargement de rapports, APllity exige d'activer I'exten-sion CURL, proposée avec PHP. Vous trouverez de plus amples informations sur la procé-dure à suivre à partir du site de PHP (http://www.php.net/curl).

Seuls les utilisateurs de PHP4 auront besoin de l'extension DOM XML proposée avecPHP4 (httpl/vvvvw.php.neUdomxml), mais remplacée par DOM sous PHPS et désormaisintégrée au noyau de PHPS. La bibliothèque APllity contrôlera dès son installation la bon-ne conformité avec ses exigences, et affichera une alerte en cas de problèmes.

Paramétrer la bibl iothèqueChaque requête soumise à I'interface de programmation AdWords nécessite une authen-tification ainsi que I'indication d'une marque du développeur censée identifier chaquedéveloppeur. Veuillez consulter I'encadré détaillant le processus à suivre pour paramétrerun compte AdWords, puis avoir accès à l'interface de programmation. Nous supposeronsdans cette partie que vous avez déjà ouvert un compte et possédez toutes les donnéesd'accès complémentaires. Afin de faciliter le processus d'authentification, la bibliothèqueAPllity utilise le fichier central intitulé authentication.ini.

En règle générale, une agence publicitaire possède plusieurs clients, chacun d'entreeux ayant accordé à l'interface de programmation de I'agence un accès à leurs comptes.Ces clients sont regroupés dans le My Client Center (MCC, ou Mon Centre Client) del'agence. Le gestionnaire du MCC est appelé gestionnaire client. La première adresseemail du gestionnaire client identifie I'agence, alors que la première adresse email de cha-que client du gestionnaire identifie le client en question. Ainsi, afin d'avoir accès à un clientparticulier, il faut vous identifier avec I'adresse email de votre gestionnaire client, votre motde passe, votre marque développeur et I'adresse email particulière du client. Ouvrez lefichier authentication.ini, et entrez-y une seule fois ces données. Vous êtes enfin prêt.

Les annonceurs peuvent choisir le coût

maximum par cl ic (CPC)qu' i ls sont prêts àpayer, alors que la note de qualité est dé-

terminée par le taux de clics (clickthrough

rate, ou CTR) sur chaque mot clé, la per-

tinence du texte de I'annonce, la perfor-

mance historique des mots clé, et d'autres

facteurs. Le système dépend donc aussi

de la pertinence des annonces.

Structure d'un compteAdWords GoogleUn compte AdWords Google se compose

de différentes campagnes. Suivant I'exem-

ple précédent, Alice devrait posséder

différentes campagnes pour les VTT et les

vélos de course. Chaque campagne con-

tient un ou plusieurs groupes d'annonces.

Ainsi, la campagne d'Alice sur les vélos

de course peut comprendre des groupes

d'annonces par fabricant. Enfin, chaque

PHP Solut ions N'4/2006

groupe d'annonces comporte une liste

de mots clé ou de critères de sites Web,

ainsi qu'une liste de créations (annonces

textuelles apparaissant sur le moteur de

recherche). Alice peut choisir le CPC maxi-

mum par mot clé qu'elle est prête à payer,

Figure 1. Structure des c/asses de la bibliothèque APllity

ou plus simplement un CPC par défaut par

groupe d'annonces. Dans le même ordre

d'idée, chaque mot clé peut avoir sa pro-

pre URL de destination vers laquelle sera

acheminé I'utilisateur lorsqu'il cliquera sur

I'annonce (comme par exemple, chaque

sous-catégorie du fabricant sur le site du

magasin de vélos), ou tout simplement

une URL générique (comme par exemple,

la principale entrée du site du magasin de

vélos). De même, les campagnes et lesgroupes d'annonces peuvent être exacte-

ment adaptés aux besoins de l'annonceur.

Les campagnes, par exemple, peuvent

être ciblées régionalement, les groupes

d'annonces peuvent être suspendus ou

complètement supprimés (lorsqu'Alice

décide, par exemple, de ne plus vendre

les vélos d'un certain fabricant). Les

rapports de performance permettent aux

annonceurs de suivre les résultats de leurs

comptes AdWords.

Interface de program-mation AdWordsAfin de gérer un système aussi com-plexe, Google s'est adapté aux besoins

des annonceurs en leur proposant une

interface plus eff icace qu'une simple ap-plication Web frontale. Google propose

donc une interface de programmation

permettant à une agence publici taire de

télécharger en une seule fois une quan-

t i té énorme de mots clé, sur laquelle

toutes les campagnes d'un annonceurpeuvent être automatiquement suspen-

dues en cas d'évènements imprévus,

et permettant à I'entrepôt d'une société

d' interagir avec le prix des mots clé cor-

respondants. L'interface de programma-

tion de Google permet de nombreuses

uti l isat ions.

www.phpsolmag.org

Contexte techniqueL'interface de programmation AdWords re-pose essentiellement sur la technologie demessage SOAP, protocole basé sur XML

et HTTP extrêmement bien supporté dansle secteur. L'interface de programmation Ad-

Words utilise des documents ou style littéral

SOAP 1.1. Afin d'accâler aux comptes Ad-

Words d'un point de vue programmation, les

utilisateurs construisent un client de servicesWeb ayant recours à I'interface de program-

mation AdWords. En regle générale, un pre

gramme client de services Web a recours àune boîte à outils censée savoir commentse connecter et interagir avec les servicesWeb. Les requêtes pouvant être traitées par

un service Web sont définies dans un fichierWSDL (Web Services Definition Language,ou langage de définition des services Web)

en XML. Le fichier WSDL décrit les opéra-tions que le service Web en question peut

réaliser, les paramètres requis pour chaqueopération, et les réponses attendues pour

chaque opération. Afln de pouvoir utiliserI'interface de programmation AdWords, les

utilisateurs râligent des programmes clients

dans le langage de leur choix (comme Java,Perl, Python, C, C++, PHP, etc.). Le Programme client envoie une requête à I'un desservices Web AdWords, comme le serviceTrafficEstimatorService ou AdGroupSer-vice. Le service en question traitera alors larequête puis renvena une réponse que leprogrcmme client devra analyser.

Raisons de proposer

des bibliothèques clientDébuter avec les services Web n'est pas

chose aisée et peut même en découragerplus d'un en raison du grand nombre deparamètres à prendre en compte que les

développeurs d'application n'ont pas forcé-ment en tête. C'est la raison pour laquelleGoogle a décidé de proposer des biblio-

thèques client comme APllity chargée defournir une couche d'abstraction aux dé-

tails des ces services Web et de les cou-vrir dans des constructions supérieures du

langage. Google propose également une

autre bibliothèque client Java, disponible

sous forme de proyet open source (httpt/

so u rcef o rg e. n et/ p roi e ct s/g o o g - a d - a p i -

c/,4. APllity propose aux développeursun accès orienté objet et facile à utiliser

à I'interface de programmation AdWordsde Google à partir du langage PHP. Vous

trouverez dans la suite du présent articleun tutoriel pratique sur I'utilisation de la

bibliothèque APllity.

Système de quotasL'interface de programmation AdWords

gère le trafic au moyen d'un système de

quotas fournissant à chaque développeur

un nombre d'unités de quotas gratuites

par mois échangeables contre certaines

opérations. Alors que certaines opéra-

tions n'exigent qu'une unité de quota,

d'autres peuvent en consommer plusieurs.

Pourquoi avoir opté pour un système dequotas ? L'interface de programmation Ad-

Words agit rapidement et efficacement afinde pouvoir accepter d'un point de vue pro-

grammation des milliers d'opérations. Afin

d'empêcher le système de recevoir plus

d'opérations qu'il ne peut en gérer, Googlea recours à un système de quotas capablede redistribuer des unités de quotas gratui-

Listing 1. Fichier authentication.ini sous APllity

; S u r l - e f i c h i e r a u t h e n t l c a t r o n ' i n r ;

; c e f i c h i e r c o n t r ô l - e I ' a u t h e n t i l i c a t i o n d e I ' u t i l i s a t e u r s o u s A P I I j . t y .

, ' P o u r p e r m e t t r e à A P I l i t y d e l e l i r e , i l d o i t ê t r e a p p e l e

. I a r r f h e n t i e e f i n n - i n i t .

: T , : s v n t â x e ' l e c e f i c h i . e r e s t d ' u n e s r m p l i c i t é e x t r ê m e ' L e s l i g n e s

. ^ ^ m m ô n - â n i n : r i l n n o i n f r r i r o i l l e e t 1 ^ ^ ^ ^ - ^ ^ ^ ^ L l - ^ ^ ^ ^ ô n f f ô r t c i m n l ê m e n t' - - ç ù c J P d u c J ! f o l l ç ù J r r " y f L t r r v r r r

: i o n o . é s e n s i l e n c e .

E m a i l = " y o u r E m a l I G s o m e I S P . t l d "

p a s s w o r d = " y 0 u R 5 e c R 3 L "

D e v e l o p e r T o k e n - " y O u r D 3 v 3 l 0 p 3 R T 0 k 3 n "

C l i e n t E m a i l = " y o u r C l i e n t s E m a i l @ s o m e I S P ' t l d "

Listing 2. Extrait des données de sortie de l'application hello wotld

A r r a y (

t 0 l = > C a m P a i g n O b j e c t (

lname] =) Some Name

I i d ] = > 1 2 3 4 5 6 1 8

I s t a t u s ] = > A c t r v e

I s t a r t D a t e ] = > 2 0 0 6 - 0 3 - 3 1 T 1 1 : 0 3 : 2 1 ' 0 0 0 2

I e n d D a t e ] = > 2 0 0 7 - 0 1 - 0 1 T 0 7 : 5 9 : 5 9 ' 0 0 0 2

I d a i l y B u d g e t ] : > 5 6 7

I l a n g u a g e s ] = > A r r a y (

I o ] = > e n

I r ] = > p l

1 2 ) = > f . r

)I g e o T a r g e t T Y P e ] = > c o u n t r i e s

I g e o T a r g e t s ] = > A r r a y (

[ 0 ] : > u K

[ 1 ] = > P L

[ 2 ] = > G B

)I i s E n a b l e d O p t i m i z e d A d S e r v i n g ] = > [ n e t w o r k T a r g e t i n g ] = > A r r a y (

l 0 l = > S e a r c h N e t w o r k

[ 1 ] = > C o n t e n t N e t w o r k

)I i s E n a b l e d S e p a r a t e C o n t e n t B i d s ] : > 1

))

Listing 3. Extrait des données de sorfie de l'application hello world étendue

A r r a y (

[ 0 ] = > A d G r o u p O b j e c t (

I m a x C P c ] = ; 1

lmaxCPml =1

I m a x C o n t e n t C p c ] = > [ n a m e ]

I i d ] = > 2 1 9 9 4 5 0 0 1

l b e l o n g s T o C a m p a i g n l d l = >

l c i â t 1 1 e l = > A . f i 1 7 êL J L g ! q v

= > s d s d s d

r 0 8 3 8 9 4 1

www.phpsolmag.org PHP Solutions N" 4/2006

Figure 2. Hiérarchle des objets de la bibliothèque APllity

tes mensuellement. Le nombre d'unités dequotas gratuites est déterminé selon lesdépenses totales du développeur.

Quelques précisionssur la structure dela bibl iothèque APll i tyLa bibliotheque APllity utilise une versionadaptée de NuSoap de Dietrich Ayala afinde pouvoir interagir avec l'interface deprogrammation AdWords. Son centre estapility.php (vert), lequel comprend toutes lesdifiérentes classes possibles. Chaque servi-ce Web est représenté par sa propre classe(aune). Ce système permet ainsi à quicon-que intéressé par I'installation détaillée d'unetâche particulière, de trouver facilement laclasse appropriée. L'implémentation prefère la clarté à I'optimisation de I'espace.Ceci permet aux développeurs de suivre leXML envoyé de manière inteme. Le fichierClients.php agit comme connecteur entreNuSoap, le trafic brut XML SOAP (tout engris) de I'interface de programmation etles objets PHP de niveau supérieur de labibliothèque APllity. Enfin, I'authentification,la gestion des eneurs et certains utilitairesbasiques viennent parfaire la bibliothèque.

Objets affichés dans APllitysur l'interface AdWordsComme nous venons de le mentionnerplus haut, les comptes AdWords con-tiennent des campagnes elles-mêmesdivisées en groupes d'annonces, lesquelscomprennent des créations, qu'il s'agissede mots clé ou de critères de site Web.

PHP Solutions N'4/2006

Chaque campagne et chaque grouped'annonces est identifié au moyen d'unidentifiant universel unique, alors que lescréations, les mots clé et les critères desites Web le sont par un identifiant uniqueau niveau du compte. Les campagnes

sont des objets indépendants, et tous lesobjets dérivés stockent un lien retour versI'emplacement auquel ils appartiennent.En d'autres termes, les groupes d'annon-ces stockent I'identifiant de la campagnedans laquelle ils sont compris, et lescréations mémorisent l'identifiant de leurgroupe d'annonces, et ainsi de suite. Nousavons exposé dans I'illustration ci-dessousla hiérarchie complète des objets.

ApplicationHello World sous Apll ityLa quasi totalité des tutoriaux de program-mation débute par un exemple de typehello world, et nous ne dérogerons pasà la règle. Si vous avez bien téléchargéla bibliothèque APllig, si vous I'avez bienplacée dans un dossier auquel PHP peutaccéder, et si vous avez bien entré vosdonnées d'authentification, vous êtes finprêt à démaner I'application. Tout d'abord,APllity doit être incluse (dans ce cas, il suf-fit de placer la bibliothèque dans le mêmedossier que le programme hello world):

/ / i n c l u r e 1 a b i b l i o t h è q u e A P I l i t y

r e q u i r e o n c e ( ' a p i l i t y . p h p ' ) ;

Listing 4. Etape 1, création d'une liste de fous /es critères par mots clé d'uncompte

php

/ / i n c l u r e L a b t b l i o t h è q u e A P I l i t y

r e q u i r e o n c e ' a p i l i t y . p h p ' ;

func t ion ge tA l lCr i te r iaOfAccount r r :

/ / ob ten i r tou tes Jes campaçrnes

/ / e n c a s d ' é c h e c d e c e t t e e t a p e f o n d a n e n t a l e , r e t o u r n e r L a v a L e u r f a u s s e

i f , l 9 a l l C a r n p a i g n s = g e t A l l C a m p a i g n s i i i r e t u r n f a l s e ;

/ / pour chaque canpagne, ob ten i r tous les q roupes d 'annonces contenus

f o r i $ i = 0 ; S i . s i z e O f $ a l l C a m p a i g n s r ; $ i + + :

$campaign = $a l lCampaigns $ i ;

/ / i c i , e n c d s d ' e r r e u r , s a u t e r l ' i t è r d t j o n e n q u e s t i o n

i f : l$a I lAdcroupsOfCampaign $ i = Scampaign- 'ge tA l IAdÇroups i i i con t inue, '

/ / n o u s n e v o u l o n s g u e r o u s - l e s m o t s c l e d u c o n p L e . D o n c , i n i r j a l r s e r

/ / un tabLeau chargé de conten i r ces in fo rmat jons

$a l lCr i te r iaOfAccount = a r ray i r ;/ / l o a r n e o ç q r r c r l p r z j p n r i r i r t n n o r r à i f f i r i 1 a ' n n r t r r h- , ,aque canpdqne,

/ / e t d o n c p o u r c h a q u e g r o u p e d ' d n n o n c e s , o b t e n i r t o u s . l e s n o t s c l é c o n t e n u s

f o r , 9 i = 6 ' $ i . s i z e O f r $ a l l A d G r o u p s O f C a m p a i g n t ; $ i + + l l

f o r r $ i = 6 ' $ j s i z e O f , $ a f f À d G r o u p s O f C a m p a i g n , $ i . ) ; S j + + ) :

$adGroup = $a l lAdGroupsOfCampaign r $ i $ j r ;

/ / i c i / e n c a s d ' e r r e u r , s d u t e r l ' i t e r a t i o n e n g u e s t i o n

i f r ! $ a l l C r i t e r i a = $ a d G r o u p - g e t A l l C r i t e r i a r r , c o n t i n u e ;

f o r e a c h L $ a I l C r i t e r i a a s $ c r i t e r r o n )

a r r a y p u s h , S a l l C r i t e r i a O f A c c o u n t , $ c r i t e r i o n , ;

re tu rn $a l lCr i te r iaOfAccount ;

Campaingname

id

statusstartDateendDatedailyBudgetnetworkTargetingran9uagesgeoTargetTyp€geoTarget

campaignNegativeKeywordCriteriacampaignNsgativewebsiteCriteriaisE nabledSeparatecontentBidsisE nablêdOptimizedAdSewing

AdGrDUpnam6id{ b€longs:focârpebntOr||sxcpcmexcpmmaxContâ]îlCpcdâtu8

www.phpsolmag.org

Toutes les fonctionnali tés de la bibl io-

thèque APl l i ty sont désormais d ispo-

nibles. Nous pouvons donc procéder

à l'application hello world, qui consiste,

sous AdWords, en une l iste de toutes

les campagnes d 'un c l ient . Commen-

çons par observer le code suivant :

< ?php

/ / i n c l u r e I a b i b l i o t h è q u e A P I J . i t y

/ / r a a t t i r c o n e p I r : n i l i r r r n h n r \ :! e Y u r r L v r , e u \ u y t t r v I . Y t L Y t t

/ / o b t e n i r t o u t e s l e s c a m p a g n e s d u

/ / c l ient

( r l l a r m n : i n n c = 6 4 f À l l l . a n r i a n o / \ .v o r r L q r r y o f 9 r r J

- Y c L n r r u a l l l I J a f v l r J t / t

/ / d o n n e e s d e s o r t i e d é p l a i s a n t e s m a i s

/ / f o n c L t o n n e f f e s r - s s u e s

/ / d u t a b l e a u d e s o b j e t s c a m p a g n e

e c h o " ( p r e ) " ;

p r i n t r ( $ a l l C a m p a i g n s ) ;

e c h o " < / p r e > " ;

? >

Les données de sortie s'affichent sous for-me de cliché brut du tableau des campa-gnes des clients. Lorsque votre compte necontient qu'une campagne, vous devriezobtenir des données identiques à cellesillustrées dans le Listing 2.

Une fois toutes les campagnes obte-nues, comment obtenir tous les groupesd'annonces ? Chaque groupe d'annon-ce appartient à une campagne. Nousdevons donc demander aux campagnesla l iste de tous ses groupes d'annonces,et effectivement la manæuvre est aussidirecte. N'oubliez pas que nous dispo-

sons d'un tableau de campagnes (ensupposant que nous uti l isons les varia-bles de I 'exemple précédent) :

/ / a a a o à o r À I a n r o m i À r o n r m n : o n e r ] a n sq f u y r L , L ' r u

/ / l e t a b l e a u d e s c a m p a g n e s

/ / d 1 : c n h f o n i r q a c ô r ô r r n ê q d l : n n o n e e q| | y u L r

$ a l l A d G r o u p s = $ a l l C a m p a i g n s l 0 l - >

g e t A l l A d G r o u p s O ;

/ / m ê m e s d o n n é e s d e s o r t i e b a s i q u e s

e c h o " ( p r e ) " , '

p r i n t r ( $ a l l A d G r o u p s ) ;

e c h o " < / p r e ) " ;

Vous devriez donc obtenir un ou plusieursobjets groupe d'annonces dans un ta-bleau identique à celui exposé dans leListing 2.

Listing 5. Étape 2, évènement déctencheur lançant les modifications de CPC maximum

p h p e l s e e c h o " B i d s a l r e a d y r a i s e d .

/ / v a r i a b l e s g J o b a ) e s c h a r g e e s d e d e f i n i r l - e d e b u t e t S t i l 1 l u n c h t i m e . < b r / > \ n " ;

/ / le f in de la pause de jeuner .

$ I u n c h S t a r t T i m e = " 1 1 : 0 0 : 0 0 " ; / / C ' e s t l ' h e u r e d u t r a v a i L

S l u n c h E n d T i m e = " 1 3 : 0 0 : 0 0 " ; e l s e

/ / a t c e n d r e 1 5 n i n u t e s e n t r e c h a q u e c y c l e d e c o n t r ô l e / / S t p a s e n c o r e r e d u i t e s ,

S s l e e p T i m e = 1 5 ; i f l $ b i d s l o w e r e d '

func t ion s ta r tDaypar t ingDaemon $ IunchStar tT j -me, / / rédu i re les o f f res .

$ l u n c h E n d T i m e , i f l l o w e r B i d s , $ a l l C r i t e r i a : ,

$ s 1 e e p T i m e , $ a l l C r i t e r i a = n u l - ] , $ b i d s R a i s e d = f a l s e , e x i t r " E r r o r o n l o w e r i n g t h e k e y w o r d s m a x C P C . " , '

$ b i d s l o w e r e d : f a l s e l ; e l s e

/ / s i ] e d é n o n d e p d r t a g e d e J a j o u r n é e e s t J a n c é p o u r 1 a e c h o " L u n c h T i m e e n d e d , < f o n t c o l o r = ' g r e e n r )

/ / p r e n i è r e f o j s , L e n t e r d e r e t r o u v e r l e s c r i l è r e s p a r l o w e r i n g < / f o n t > b j . d s . < b r / > \ n " ;

/ / no ts c l .é v ja un appe l de L ' in te r face de progrdnndt ron . $b ids lowered = t rue , '

/ / f e s n o t s c l - é s e r a n t e n s u i t e r e t o u r n é s à c h a q u e $ b l d s R a i s e d = f a l s e ;

/ / r é c u r s i v i t é .

i f i s n u 1 1 ' $ a I I C r i t e r i a r j

e c h o " D a y p a r t i n g D a e m o n s t a r t e d . b r / \ n " ; e l s e e c h o " B i d s a l r e a d y l o w e r e d .

o b f l u s h , ; ; S t i l l w o r k t i m e . < b r / > \ n " ;

f lush , , ;

/ / E n c a s d ' é c h e c , } e c o n p t e n ' e s t m ê m e p J u s a c c e s s i b J e / / r e t r o u v e r e L i n p r i n e r m e s d o n n é e s p r e a l a b l e n e n L

i f , ! $ a l l C r i t e r l s = g e t A l l C r i t e r i a O f A c c o u n t i r , / / p l a c é e s e n z o n e t a n p o n

e x i t i " C o u l d n o t a c c e s s t h e a c c o u n t " : ; o b f l u s h r ;, e lse f lush r ' ;

e c h o " A c c o u n t d a t a s u c c e s s f u l l y l o a d e d . < b r / > \ n " , ' s l e e p r $ s l e e p t i m e * 6 0 r ;

/ / a p p e J r e c u r s i f , r e n a r q u e : l - e t a b f e a u a l l C r i t e r i d e s t

/ / d é s o r n a i s r e n p L i e t - l e s b i t s d ' é t a t s t o c k é s s r - i e s

/ / vér i f ie r s i c 'es t f 'heure de la pause dé jeuner / / o f f res on t é té nod i f iées .

$ n o w = t i n e i ) ; s t a r L D a y p a r t i n g D a e m o n i $ l u n c h S t a r t T i m e , $ I u n c h E n d T i m e ,

/ / C ' e s t J a p a u s e d é l e u n e r $ s l e e p T i m e , S a l ] C r i t e r j . a , $ b i d s R a i s e d ,

i f r r s n o w = m a k e U n i . x T i m e S t a m p i $ I u n c h S t a r t T i m e i r & & $ b i d s l o w e r e d , ;

' $ n o w , = m a k e U n i x T i m e S t a m p r $ l u n c h E n d T i m e ) I l

/ / S i pas encore augnentées , / / Cet te fonc t ion conver t i t une durée en fo rna t IS0

i f , ! $ b i d s R a i s e d r t / / ( 1 2 : 0 0 : 0 0 ) y e r s u n e e s t a m p j 7 I e t e m p o r e l l e U N I X

/ / augnenter Les o f f res func t ion makeUnixT imestampt$ isoT imet l

i f I ! r a i s e B i - d s i $ a l l C r i t e r i a : ) $ t i m e C o m p o n e n t s = s p l i t i " : " , $ i s o T i m e ) ;

e x i t i " E r r o r o n r a i s j . n g t h e k e y w o r d ' s m a x C P C . " l ; r e t u r n m k t i m e r $ t i m e C o m p o n e n t s i 0 r , $ t i m e C o m p o n e n t s 1 ,

e l s e $ t i m e C o m p o n e n t s 2 r , d a t e t " m " ) , d a t e i " d " ) ,

e c h o " L u n c h T i m e s t a r t e d , < f o n t c o l o r = ' r e d ' ) d a t e l " Y " r I , ' :

r a i s i n g < / f o n t > b i d s . < b r / > \ n " ; / / L a n c e r l e d e n o n ( e t e x é c u t e r l e " p o u r t o u j o u r s " )

S b i d s R a i s e d = t r u e ; s t a r t D a y p a r t i n g D a e m o n i $ l u n c h S t a r t T i m e , $ l u n c h E n d T i m e ,

$ b i d s l o w e r e d = f a l s e , ' $ s l e e p T i m e r ;

www.phpsolmag.org PHP Solut ions N'4/2006

SOAP XML

"Virtualization" Of the AdWords API By the Web Server

Figure 3. Extrait d'une application APllitAx utilisant la bibliothèque APllity combinée à AJAX

Nous pouvons poursuivre la manoeuvreet appeler serArlAdGroups O SUr tOuS leS

objets campagne, puis qerAttcrearives o

9t serAllcrirerla O de manière récursive

sur chaque objet groupe d'annonces jusqu'à

obtention de I'arborescence complète du

compte client. C'est ce que vous pouvez

observez dans le pro1et démo proposé avecla bibliothèque APllity.

Traiter les erreurs et laprogrammation défensivell anive parfois que des ereurc surgissent.Tous les programmeurs seront sans douted'accord avec I'affirmation suivante: dèslors qu'un service Web à distance est impli-qué dans un processus, il est d'autiant plusimportant de bien gérer les erreurs. Or, labibliothèque APllity permet non seulementde coder directement mais également d'éla-borer une programmation défensive, selonla convention suivante :

. retourne la valeur fausse en cas deproblème quelconque,

. sitout se déroule bien :. retourne l'élément à retourner,. retourne la valeur vraie en I'ab-

sence d'élément à retourner.

Seules exceptions à cette convention, lesfonctions d'obtention d'objets simples, dansla mesure où elles nécessitent un objet crééavec succès. La fonction addcampaisnll,par exemple, consiste à ajouter, comme sonnom I'indique, une campagne, puis retoumecette campagne tout juste ajoutée. Ainsi, enI'absence de problème, vous pouvez atten-dre un objet campagne en tant que valeurretoumée, ou une valeur fausse lorsque

PHP Solutions N'4/2006

I'interface de programmation AdWords,pour certaines raisons, n'aime pas votrecampagne. ll existe donc deux possibilitésde coder:

i f ( l $ c a m p a i g n O b j e c t = a d d C a m p a i S n ( . . . ) ) {

/ / t r a i t e m e n t d e I ' e r r e u r

t

pr j -n t_ r ( $campaignOb j ec r ) ;

C ^ . h h . l a - ô H : ^ ^ t s - - À ^ a : m n r i n n / \ .v u o l r P a r 9 r l u ! J e u L - d u u v o . . r I J a r g r . t . . . , t ,

p r i n t _ r ( S c a m p a i g n O b j e c c ) ;

Toutes les eneurs sont plaées dans la pilede fautes. Ce comportement est toutefois

Asynchronous XMLOr JSON Response

(lo'

@

Web Browser Of the APlltAx User

Listing 6. Étape 3, fonctions de modification des objets

php

f u n c t i o n r a i s e B i d s S a l I C r i t e r i a ,

f o r e a c h 9 a l l C r i t e r i a a s S c r i t e r i o n

i f I $ c r i t e r j . o n - s e r M a x C p c $ c r i t e r i o n - g e t M a x c p c

re turn t rue ;

f u n c t i o n l - o w e r B i d s $ a I l C r i t e r i a r

f o r e a c h , S a L l C r i t e r i a a s $ c r i t e r i o n

i f ! S c r i t e r i o n - s e t M a x C p c $ c r i t e r i o n - g e t M a x C p c

re turn t rue , .

r e t u r n f a l s e ;

0 , 2 ' , , r e t u r n f a l s e ;

Listing 7. Fichier PHP intermédiaire exemplaire

p h p h e a d e r " C o n t e n t - t y p e : a p p J - i c a t i o n / x m l ; C h a r s e t = U T F - 8 " : ; ,' , p h p

e c h o u t f B _ e n c o d e ; " . : x m l - v e r s i o n = ' 1 . 0 ' e n c o d i n g = ' 9 1 a - t t , \ n " r ;/ / i n c l u r e L a b i b l i o t h è q u e A P I J i t y

i n c l u d e t ' . / a p i l i t y / a p j - I L t y . p h p ' ) ;

$ a u t h e n t i c a t i o n C o n t e x t - s e t E m a i _ 1 r $ P O S T ' e m a i I ' , r , .

9 a u t h e n t i c a t j , o n C o n t e x t - s e t P a s s w o r d i $ _ P O S T ' p a s s w o r d ' ) , '

$ a u t h e n t i c a t i o n C o n t e x t - s e t T o k e n i S _ P O S T , d e v e I o p e r T o k e n , I ;$ a u t h e n t i . c a t i o n C o n t e x t - s e t C l i e n t E m a i l r $ P O S T ' c l i e n t E m a i l ' I ;

S c a m p a i g n O b j e c t = c r e a t e c a m p a i g n O b j e c t i S P O S T ' ' i d ' I ;i f I ! $ c a m p a i g n O b j e c t ,

$ f a u ] t = a r r a y p o p $ f a u l t S t a c k , .

$ f a u l t - , p r j . n t F a u l t I I ;. e l s e ;

9 x m L . = $ c a m p a i g n O b j e c t - ' t o X m l r : ;

r r f f Q o n n n À a ( w m l

l-j

www.phpsolmag.org

très flexible dans la mesure où la pile de

fautes stocke les fautes dans un format

d'objet de fautes générique, et permet ainsi

de convertir à temps ces objets fautes en

mesffiges d'eneur HTML, en texte simple,

ou en XML, ou en rien du tout, selon les

besoins spécifiques du développeur.

Nouveau statutAvec ce que vous venez d'apprendre, vous

pouvez désormais créer votre propre appli-

cation ftontale Web selon vos goûts, votre

propre programme de téléchargement vers

le serveur, ou une application de lancement

de rapport exécutable en un seul clic. Et la

liste des outils à créer peut s'allonger. llvous

suffit simplement de connecter les fonctions

disponibles puis de transformer les données

de sortie de la bibliothèque APllity en HTML

ou de renseigner certains éléments de for-

mulaires avec les données restituées. Ou

encore, si vous optez, par exemple, pour un

outil de téléchargement vers le serveur, divi-

sez un fichier Excel avec tabulation comme

séparateur au moyen d'un grand nombre

de mots clés aux anêts de tabulation et aux

sauts de ligne, puis remplissez ce fichier

au moyen des fonctions d'ajout de la biblio-

theque APllity. La bibliotheque permet aux

annonceurs, certiainement satisfaits de la

capacité d'APllity, de faire déjà beaucoup de

choses. Mais le travail devient vraiment inté-

ressant au moment d'ajouter de I'interaction

et de I'automatisme.

Premier programmesérieuxEn termes d'annonces en ligne (mais pas

seulement), diviser la joumée en plusieurs

tanches d'affichage de difiérents types d'an-

nonces est un concept important. Les an-

nonces ciblent généralement une population

particulière et ce que cette audience ciblée

retient plus particulièrement selon le créneau

horaire. Rappelez-vous dAlice et de son

magasin de vélos. Les cyclistes travaillentgénéralement dur pendant la joumée, puis

se détendent sur le Web pendant leur pause

déjeuner. ll semble donc plus intéressant de

fixer le nombre maximum de CPC dans cet-

te tranche horaire afin de générer le plus de

conversions possibles, et râluire le CPC (ou

même suspendre complètement I'annonce)

pendant la période creuse.Objectif : notre tâche ici va consister

à programmer un démon de partage de lajoumée très élémentaire censé fonctionner

toute la joumée, et toujours augmenter le

CPC par critère de mot clé entre llheures

et 13 heures, disons de 0,20 Ê (Alice vit

à Londres). Étape 1 : Afin de faire fonc-

tionner ce programme, il faut retoumer au

niveau des critères par mots clé du compte

d'Alice. ll suffit pour ce faire d'étendre

l'exemple hello wofld, exposé plus haut.

Comme nous n'avons besoin que d'une

liste de tous les critères par mots clé, il est

inutile de stocker I'origine de chaque critèrepar mot clé au moyen d'une structure com-

plexe de tableaux (nous pounions même

remonter les conespondances, si nous

le souhaitions, avec la propriété de I'objet

belongsToAdGroupld de chaque critère par

mot clé). Nous utiliserons toutefois une pro'

grammation défensive par souci de flabilité.

Veuillez consulter le Listing 4.Bien que fondamentale pour retrouver

les données la première fois, cette première

API|IT Dctno

fnra/lLr S.û.

Entrr Your Logrhr Datet

@

staùr3

oÂ.ft.

Pr,ltd

st tiD.t coaoat

lffiii-r'æ| lffi-orfmgal

Ddlylut|.t

lzet

ffiffi Lrreo.e.i t;iï G.oTttgtrt3 oDdmr

O oooel.Statdltsotcrll*Toftt cortrytl.|Jtnod.

Cc[irrcCoulùiotOntrrô

Ra(iorit

t eottr3rgûabCqtantlJidf

f-sd-\\-ÈrsJ

f- su -l

I orp*e I\--PssoJ

ldô-olura.kdatst|c1Lp.l?l:ûOlw.otd.t EndTfitl|liiffilw.d.ndstrfiTl$ol2ræælvY..krfid EndtIm.

rffi]\-es!rl-,,

Logùook

Figure 4. Pincipe APllitAx

www.phpsolmag.org PHP Solutions N'4/2006

étape ne doit pas nécessairement être réalisée tous les jours

surtout lorsque les mots clé d'un compte demeurent les mê-mes pendant une certaine période de temps. En pratique, lesdonnées sont stockées dans une base de données locale etuniquement contre-vérifiées de manière périodique par rapportaux données du moment. Dans cette exemple d'application,nous nous contenterons, par souci de simplicité, de téléchargerles critères par mots clé une seule fois, puis de passer à cha-que fois les données ainsi obtenues par un appel de fonctionrécursive en omettant l'étape de contre-vérification. L'objectif,ici, n'est pas d'écrire un programme hautement efficace, maisplutôt compréhensible.

Étape 2 : une fois tous les critères par mots clé disponibles,il nous faut définir certains évènements déclencheurs afïnd'augmenter le CPC maximum par mot clé (puis de le réduireensuite). Dans notre exemple, nous allons prendre le début etla fin de la pause déjeuner comme évènement déclencheur. Ledémon de partage de la joumée devra ensuite contrôler régu-lièrement I'heure de la pause déjeuner. Si nous anivons danscette tranche horaire, le démon doit alors augmenter les ofires(mais en une seule fois), et dans le cas contraire, le démondevra les réduire (là aussi, en une seule fois), et, dans tous lesautres cas de figure, le démon poursuivra tout simplement satâche. Nous devons donc comparer difiérentes tranches horai-res. L'estiampille temporelle UNIX nous permettra de procâ1erplus facilement, comme l'illustre le Listing 5. Étape 3 : il ne resteplus qu'à ajouter les fonctions permettant de modifier le CPCmaximum. Les deux fonctions peuvent être combinées en uneseule. ll serait également possible de passer les modificationsen tant que paramètre de cette fonction, mais nous avons optépour une conception plus flexible, et certainement plus utile lorsd'une future utilisation. Veuillez consulter le Listing 6.

Défauts de cette approcheVous venez de créer votre propre démon de partage de jour-née. Ce programme n'est rien de plus qu'une illustration duconcept, et beaucoup d'éléments mériteraient encore d'êtreaméliorés, comme par exemple la récursivité, loin d'être la fa-

çon la plus judicieuse de programmer un démon de partage dejoumée en temps réel. Revenez un peu en anière: pourquoiavons-nous choisi cette approche ? Nous devions stocker laliste de tous les critères. Le protocole HTTP est sans état, desorte qu'au moment de recharger une page, tout a disparu. llserait possible d'utiliser des variables de session, mais dès quela quantité de données devient trop importante, cette méthodese révèle elle aussi impossible à appliquer. Nous pounionsrecharger I'ensemble des données, mais il ne s'agit pas de lameilleure décision, pour deux raisons: cette méthode prendtrop de temps, et coûte en quotias de valeur. Pour allez droit aubut, ilfaut avoir recours à une sorte de couche de persistance.Cette couche figure dans la liste des améliorations à apporterde l'équipe de programmation de la bibliothequeAPllity. Elle de.vrait faciliter I'int{Tration des bases de données afin de garantirune certaine persistance. Un premier jet de schéma d'une basede données MySQL issu de deux collaborateurs open sourceau projet APflity est déjà disponible (httpl/www.adoptimize.de/glossar/mysql4. 1 . 1 1 .sheme.apility.0.4.htmt).

Cette approche comporte toutefois une autre défaut plusévident: chaque opération prend un certain temps, et I'uti-

PHP Solutions No 412006

Flave Fun Prrynûl

Maguma Workbench est un environnement dedéveloppement professionnel pour les langagesPHP et Python.

Maguma Open Studio est un environnement dedéveloppement Open Source pour PHP.

Maguma - pour le plaisir de programmer!

Plus d'information:

www.maguma.com

Maguma

I

I

)

Créer un compte AdWords et s'inscrire à un accèsà I'interface de programmationVous aurez tout d'abord besoin d'un compte AdWords. Allez sur la page d'accueil du

site d'AdWords, puis suivez les instructions de I'assistant de création de compte : httpsl/

a dwo rd s. goog I e. co m/se I e cUsta rte r/ sig n u p/ F o rk -Une fois votre compte AdWords créé et confirmé, il vous faut envoyer vos données

bancaires afin d'activer votre compte. Vos annonces prendront ensuite forme, et vous pou-

vez continuer en vous inscrivant à un accès à I'interface de programmation. Allez sur le site

httpst/adwords.google.com/select/ApiWelcome, puis entrez vos données de connexion au

compte. Un assistant vous aidera ensuite à créer un compte My Client Center (MCC). Vous

trouverez ensuite dans l'onglet intitulé My Account (Mon compte) une nouvelle page sous

le titre de AdWords APt Center (Centre de I'interface de programmation AdWords). Votre

marque de développeur ainsi que les informations sur I'utilisation de I'interface de program-

mation, y compris sur les quotas, y seront affichés. Les trois tutoriaux multimédias suivants,

disponibles en ligne, vous faciliteront davantage vos premiers pas avec l'interface :

. http !/seru ice s.google. com/aw p/en_u s/b reeze/264836/i ndex. html

. http ://services.google.com/awp/en _u s/b reeze/2677 1 8/index. htm I

. http://services.google.com/awp/en_us/breeze/264848/index.html

pour de plus amples informations, n'hésitez pas à poster vos questions sur le forum des

développeurs de I'interface de programmation AdWords :

. hftp://groups.google.com/group/adwords-api

lisateur ne voit rien à l'écran pendant le

traitement réalisé par I'interface de program-

mation AdWords. ll est impossible d'accé-

lérer le temps de réponse de I'interface deprogrammation AdWords, mais plutôt de

cumuler plusieurs requêtes de I'interface deprogrammation AdWords en une seule fois,

de manière à pouvoir continuer à travailler

utilement pendant le traitement d'une re-quête. Une requête pounait, par exemple,

consister à charger un rapport important,pendant qu'une autre serait de soumettre

de nouvelles campagnes. Malgré l'absence

de traitement en plusieurs unités d'exécu-

tion des séquences utilisateurs sous PHP,

une combinaison intelligente de plusieurs

techniques pounait permettre d'adapter des

requêtes de l'interface de programmation en

traitement multi-processus.

APllity + AJAX = APllitAxUn des termes phare de cette année pro-

bablement le plus utilisé, AJAX (acronymepour Javascript et XML), permet, comme

son nom I'indique, de transférer des don-

nées de manière asynchrone. C'est ceque signifie le 'A' dans AJAX. Or, c'est

exactement ce dont nous avons besoin.

Mais que veut dire le'X'? La bibliothèque

APllity propose des objets PHP facilement

convertissables en XML :

$someAPI l i tYObj ec t -> toxml ( ) ;

Les objets APllity peuvent ainsi être passés

sous forme de réponse à une requête A"JAX.

Restent le 'A' pour asynchrone et le'J' pour

Javascript. Comment des techniques difié-

rentes peuvent-elles fonctionner ensemble ?

L'idée est très simple. Nous avons d'un côté

I'interface de programmation AdWords, le

navigateur Web de I'utilisateur de I'autre, et

la bibliothèque APllity entre les deux. Dans

le navigateur Web, nous avons un site Web

tout à fait normal contenant des formulaires

et du texte. Chaque fois que I'utilisateur sou-

met certaines modifications ou programme

un rapport, etc., une requête de type XML

HTTP, contenant les paramètres de la fonc-

tion APllity sous forme de données norma-

les HTTP POSI est alors lancée. Une page

PHP intermédiaire analyse les données

POST puis appelle la fonction native APllity

conespondante. Cette page intermédiaire

foumit le résultat de la fonction au format

XML ou JSON, de manière à faciliter I'ana-

lyse réalisée par le navigateur Web de I'uti-

lisateur sur la réponse. Dans la mesure où

la page PHP se situe sur un serveur Web

(local) où APllity est installée, elle virtualise

en quelque softe I'interface de programma-

tion AdWords pour permettre à I'utilisateur

d'y placer plusieurs requêtes.

ExigencesAfin de faire fonctionner le principe APllitAx'

APllity ne doit absolument pas être ver-

beuse. En efiet, chaque alerte produite par

PHP détruirait la structure XML dans le fi-

chier PHP intermédiaire. C'est la raison pour

laquelle APllity propose un mode appelé

Si'Tence Stea/fh Mode dans lequel toutes

les alertes PHP et les propres messages

d'alertes d'AP I lity sont désactivés. Toutefois,

les eneurs de I'interface de programmation

AdWords seront toujours interceptées dans

la pile des eneurs, sans être affichées. ll est

assez utile de choisir XML comme format

d'eneur au moment de lancer APllity en

tant que bibliothèque integrée. Par nature, le

mode Silence Steafth Mode rendra difficile

à trouver les eneurs ne découlant pas de

I'interface de programmation. En règle gé-

nérale, le fichier PHP intermédiaire doit gé-

nérer du XML au moins valide, même lors-que aucun paramètre POST n'est envoyé.Vous pouvez tester cette fonction en lançant

le fichier indépendamment. Désactivez puis

réactivez le mode Silence Sfea/th Modependant la session de déboguage peut per-

mettre de trouver de simples ereurs de type

vaiables non4éclarées.

Fichier PHPintermédiaire exemplaireNous allons décrire dans cette partie un

fichier PHP intermédiaire exemplaire afin

d'éclaircir le concept fondamental. Nous

devons tout d'abord paramétrer I'en{ête de

sorte à déclarer le contenu sous le format

XML. À partir de maintenant, nous sommes

entièrement liés à cette déclaration. Chaque

donnée en texte simple produira une elreur

d'analyse. La requête XML HTTP ne trou-

vera donc jamais son résultat et attendra in-

définiment. La méthode de programmation

défensive exposée plus haut prend icitoute

son importance dans la restitution des résul-

tats attendus. L'authentification est désor-

mais réalisée de manière dynamique grâce

à I'objet global $authenticationcontext

ainsique les données HTTP POST. En cas

d'eneurs, le snippet du code intermédiaire

affiche un message d'eneur de I'interface

de programmation AdWords. Lorsque tout

se passe conectement, I'objet APllity resti-

tué campagne est alors converti au format

XML

Sur lnternet. Paged'accueild'APllity

- http ://google-apility. sou rceforge. neU. Page consacrée au projet APllity sur

SourceForge- https t/sou rceforge. neUprojects/google-apilM

. Références à APllity- http t/goog I e a pi I ity. so u rceforg e. n eUA P I I ity-Reference Standalone.html

. Forum consacré au support d'APllity- http ://grou ps-beta.google. com/group/adwords-api-php

. Page d'accueil de I'interface de programma-tion AdWords- http l/www.google. com/apis/adword s/index.html

www.phpsolmag.org PHP Solutions N" 4/2006