Webservice de pré-inscription Camsympa

Table des matières

  1. Présentation
  2. Règles d'utilisation
  3. Méthodes d'utilisation
  4. Gestion des réponses
  5. Exemple d'utilisation du webservice avec la méthode JSON et la framework jQuery

Présentation

Ce webservice permet de "pré-inscrire" un client sur CamSympa, uniquement à partir de son adresse email. Une fois la pré-inscription effectuée, le client doit être renvoyé sur l'url fournie par le webservice (page de paiement). Si le client prend son essai gratuit, il pourra ensuite finaliser son inscription (choix de son identifiant, son mot de passe, etc...).

Règles d'utilisation

Seules les pré-inscriptions d'adresses emails valides et appartenant à des clients réels sont autorisées. Il est strictement interdit de pré-inscrire des adresses emails incorrectes, inexistants, falsifiées, jetables, etc.

Le client doit toujours être envoyé sur l'url fournie par le webservice. Vous pouvez l'envoyer directement sur cette url ou le faire passer via une page de redirection (pour tracker les clics par exemple). Mais dans tous les cas, le client doit arriver au final sur l'url fournie par le webservice.

Il est strictement interdit de tenter de finaliser la pré-inscription d'un client à sa place.

A noter :

En cas d'abus, l'accès au webservice pourra être coupé sans préavis. Toute pré-inscription ou finalisation de pré-inscription frauduleuse pourra être annulée.

Méthodes d'utilisation

Ce webservice peut-être utilisé via 2 méthodes d'échange de données : le XML ou le JSON

Quelque soit la méthode utilisée l'url d'appel est identique:

http://r.camsympa.com/u.php

les variables indispensables sont:

Pour la méthode JSON il faudra ajouter 2 variables complémentaires :

Exemples d'urls appelées

avec la méthode XML:

http://r.camsympa.com/u.php?id=10000&tracker=preinscrit_cam&email=toto%40example.com

avec la méthode JSON:

http://r.camsympa.com/u.php?id=10000&tracker=preinscrit_cam&email=toto%40example.com&format=json&callback=maFonction

maFonction est le nom de la fonction que vous utiliserez pour gérer les données reçues via l'appel au webservice.

Attention à bien urlencoder les valeurs des variables email et tracker!

Gestion des réponses

Les messages et les codes envoyés lors de l'utilisation du webservice sont identiques quelque soit la méthode utilisée. Mais nous utilisons ici pour une meilleur compréhension les résultats d'une sortie XML.

Réponses possibles en utilisant la méthode XML

La pré-inscription est OK. Il faut renvoyer le client sur l'url contenue dans link

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<service>
<code>OK</code>
<result>Submission OK: Subscription OK</result>
<link>http://r.camsympa.com/u.php?uid=852145268&key=f5d2c5d1e4f5c2sz7e8f52c7ad85f7f5fd8f8b54</link>
</service>

Erreur en cas d'appel incorrect du webservice:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<service>
<code>Error1</code>
<result>Access Error : Invalid URL</result>
<link></link>
</service>

Erreur en cas d'email invalide:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<service>
<code>Error2</code>
<result>Validation Error : Invalid Email</result>
<link></link>
</service>

Erreur en cas d'email déjà inscrit:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<service>
<code>Error3</code>
<result>Submission Error : Existing Email</result>
<link></link>
</service>

Exemple de retour en utilisant la méthode JSON

Si vous optez pour la méthode JSON le format de retour sera de ce type :

maFunction({"version":"1.0","code":"Error2","result":"Validation Error : Invalid Email","link":null})

maFonction est la valeur du paramètre callback que vous avez fourni lors de l'appel au webservice. Notez que cette fonction prends pour variable un objet javascript contenant la réponse du webservice.

Exemple d'utilisation du webservice avec la méthode JSON et la framework jQuery

le HTML, le CSS et le javascript vont ensemble. Si vous modifiez les attributs class et/ou id du HTML vous serez obligés de faire de même pour le CSS et le javascript. Les données importantes sont les suivantes:

Le code HTML

<div id="cam_ws">
	<label for="cam_ws_email">inscription à camsympa</label>
	<input type="text" id="cam_ws_email">
	<button class="cam_ws_submit">inscris-toi</button>
</div>

Attention: la balise cam_ws_wait étant générée via javascript elle n'est pas reprise dans le code HTML

Le code CSS

Bien sur vous pouvez modifier à votre aise le CSS.

#cam_ws { 
	clear:both; overflow:hidden; margin:0 auto 2em; padding:6px; width:450px; border:none; 
	background:#445d9f; color:#333; 
	font:normal 100% "Segoe UI", verdana, helvetica, arial, sans-serif; 
	-moz-border-radius:11px; -khtml-border-radius:11px; -webkit-border-radius:11px; border-radius:11px;
	-moz-box-shadow:#666 0 0 18px; -webkit-box-shadow:#666 0 0 18px; -khtml-box-shadow:#666 0 0 18px; box-shadow:#666 0 0 18px; 
}
#cam_ws label { 
	display:block; margin:0; padding:0; 
	background:transparent; color:#e5e5e5; 
	font-weight:bold; font-size:120%; 
	text-shadow:0 -1px 1px rgba(0,0,0,0.25); 
}
#cam_ws input,
#cam_ws button { 
	margin:.3em 0; padding:3px 5px; border: 1px solid #e5e5e5; 
	font:bold 100% "Segoe UI", verdana, helvetica, arial, sans-serif; 
	text-align:center; text-shadow:0 -1px 1px rgba(0,0,0,0.25); 
	-moz-border-radius:5px; -khtml-border-radius:5px; -webkit-border-radius:5px; border-radius:5px; 
}
#cam_ws input { 
	float:left; width:330px; 
	background:#fff; color:#444; 
}
#cam_ws button { 
	float:right; width:100px; 
	background:#ffb515; color:#fff; 
	cursor:pointer; 
}
#cam_ws button:hover { 
	background:#ff472f; 
}
#cam_ws em { 
	clear:both; display:block; margin:.3em auto; 
	background:transparent; color:#ffb515; 
	font-weight:bold; text-align:center; 
}

Le code Javascript (N'oubliez pas d'inclure la librairie jQuery sinon ce script ne fonctionnera pas!!)

Pour adapter ce script à votre site il faut modifier les lignes 5 et 6 en indiquant votre id_webmaster et votre tracker.
Pour rendre le script encore plus spécifique, vous pouvez modifier :

jQuery(function($) {
	var remote_subscription = function (params) {
		var uri = 'http://r.camsympa.com/u.php?callback=?', 
		defaults = {
			'id': 10000, 
			'tracker': '_test_inscription_json', 
			'format': 'json'
		}, 
		getResults = function (data) { //data represente les données reçues via appel JSON au webservice
			switch (data.code) {
				case 'OK':  
					window.location = data.link; 
					break;
				case 'Error1': //les arguments soumis sont imcomplets
					$("#cam_ws_wait").html(data.result);
					break;
				case 'Error2': //l'email soumis est invalide
					$("#cam_ws_wait").html(data.result);
					break;
				case 'Error3': //la personne est deja inscrite
					$("#cam_ws_wait").html(data.result);
					break;
				default: //ne devrait jamais arrive
					$("#cam_ws_wait").html('une erreur inconnue vient d\'avoir lieu'); 
					break;
			}
		},
		options = $.extend({}, defaults, params);
		$.getJSON(uri, options, getResults);    
	}; 
	$('.cam_ws_submit').click(function(){
		var txt = 'Traitement en cours',
		params = {
			'email' : $.trim($('#cam_ws_email').val()) //on recupere l'email du client ici
		};
		if ($('#cam_ws_wait').length == 0) {
			$('#cam_ws').append('<em id="cam_ws_wait">' + txt + '</em>'); 
		} else {
			$("#cam_ws_wait").html(txt);
		}
		//on inscrit le client via la fonction remote_subscription
		remote_subscription(params);
		return false;
	});
});

↑ table des matières ↑