Útmutató az integrációhoz
1. Adatkinyerés integráció A Springtab integrálás folyamatát vesszük most végig egy meglévő (de FB kliens oldali integráció nélküli) weboldalon. 1.1 Facebook alkalmazás létrehozása Ha az oldalhoz már létezik facebook alkalmazás, akkor az 1.3. lépésig a folyamat kihagyható. A https://developers.facebook.com/ oldalon hozzuk létre egy új alkalmazást: Válasszuk az advanced setup opciót, majd adjunk meg egy tetszőleges Display nevet és kategóriát, névteret nem szükséges megadni: Az alkalmazás létrejötte után rögtön láthatjuk az alkalmazáshoz tartozó FB App ID-t, ez a további integrációnak fontos része, így jegyezzük fel:
1.2 Facebook alkalmazás publikálása Az eddig létrehozott alkalmazás csak az adminisztrátorai, feljelsztői és tesztelői számára érhető el, így szükséges az alkalmazást publikálni ahhoz, hogy mindenki használhassa. Ezt két lépést kell megtenni, a Settings fül alatt lévő Contact Email résznél meg kell adni egy létező email címet: Valamint a Status & Review résznél publikálni kell az alkalmazást: Ezt követően az alkalmazás már minden felhasználó számára elérhető lesz. 1.3a Facebook alkalmazás integrálása weboldalba A weboldalba történő integrálásnál szükségünk van egy publikusan elérhető weboldalra (a példában http://example.org lesz), valamint hozzáférésre az oldal forráskódjához. Első lépésként az online felületen hozzuk létre egy úgynevezett Platformot, amin keresztül a belépési folyamat gond nélkül végre tud hajtódni. A Settings fülnél kattintsunk az Add platform gombra, majd a Website opciót válasszuk ki:
Ezt követően adjuk meg ugyanazt az oldalt, ahol az integrációt el kívánjuk végezni: Az adatok elmentése után kattintsunk a Quick start gombra, ahol a weboldalba illesztendő kódokat találjuk majd. A jelenlegi (2.2-es sdk) alapján ez a kód a következő: <script> window.fbasyncinit = function() { FB.init({ appid : '390420111133206', xfbml : true, }; version : 'v2.2' (function(d, s, id){ var js, fjs = d.getelementsbytagname(s)[0]; if (d.getelementbyid(id)) {return;} js = d.createelement(s); js.id = id; js.src = "//connect.facebook.net/en_us/sdk.js"; fjs.parentnode.insertbefore(js, fjs); }(document, 'script', 'facebook-jssdk')); A fenti kódot a <body> tag után közvetlenül kell elhelyezni. A fenti kódot két ponton kell nagy valószínűséggel módosítani, ha nem angol, hanem mondjuk magyar nyelven szeretnénk az API-t használni, akkor a connect.facebook.net/en_us/sdk.js helyett connect.facebook.net/hu_hu/sdk.js fájlt kell megadni. Illetve minden esetben ellenőrizzük, hogy az appid megegyezik-e az alkalmazásunk azonosítójával. 1.3b Facebook alkalmazás integrálása tab alkalmazásba A tab alkalmazás esetében az 1.3a weboldal integrációhoz hasonlóan egy új platformot kell létrehoznunk, viszont mint Page Tab platform:
A Tab alkalmazás esetében rendelkeznie kell az oldalunknek egy valid, tényleges tanúsítók által aláírt https certificattel, ugyanis a Secure Page Tab URL részhez ezt kell megadni. A weboldalba illesztett rövid kódot kell itt is a tab alkalmazás alapját adó oldalon elhelyezni, az integráláskor az 1.3a esettel megegyező módon. 1.4 Springtab integrálás A Springtab adatkinyerésének integrációjához az előbb elkészített weboldal kódjába kell beilleszteni a Springtab adminisztrációs felületén látható kódot. Az adminisztrációs felületen a kampányok szerkesztésénél van egy Code fül, ahol a kód elérhető. <script type="text/javascript"> var _springtab=_springtab []; (function(){var a=document.createelement("script");a.type="text/javascript";a.async=!0;a.src="//js.s pringtab.com/t1.js";var b=document.getelementsbytagname("script")[0];b.parentnode.insertbefore(a,b)})();
A fenti kódot a </head> rész elé kell beilleszteni. A fent látható kód minden kampány esetében más, a kampány azonosítója az urlbe van kódolva, így mindig ellenőrizzük, hogy a megfelelő kampányhoz készült kódot illesztettük be. A springtab adatkinyerés csak és kizárólag olyan felületeken működik, ahol a FB kliens oldali integrációja is megjelenik a springtab kóddal együtt. 2. Személyre szabás integráció A Springtab személyre szabás funkciójának integrációjához az adatkinyerési integrációban leírt lépések elvégzése szükséges. A továbbiakban feltételezzük, hogy ezek a lépések hiánytalanul és hibátlanul elkészültek. Az elhelyezett springtab kódrészlet egy külső javascriptet tölt be az oldalba, ez a kód már tartalmazza a felhasználó klaszterbe sorolását, így további lekérdezés nem szükséges. Részletesebben a 4. fejezetben tárgyaljuk a script működését. 2.1 Személyre szabás tartalom elrejtessel Amikor a felhasználó meglátogatja az oldalunkat, akkor a rendszer automatikusan besorolja őt a megfelelő klaszterbe, a klaszterbesorolás eredményéről pedig értesíti a weboldalt. Ekkor az alap működés az, hogy az összes.springtab osztályú DOM elem közül eltávolítja a kód azokat, amik nem tartalmazzák az spt_<klaszter_azonosító> -t. Például: <div class= springtab spt_2 > </div> <div class= springtab spt_1 spt_2 > </div> <div class= springtab spt_1 spt_3 > </div> Ha a 2-es klaszterbe esik a felhasználó, akkor a harmadik div nem fog megjelenni az oldalon. Ha az 1-es klaszterbe, akkor pedig az első div nem fog megjelenni. Ehhez az integrációhoz nem szükséges semmilyen extra javascript kódot elhelyezni az oldalon. 2.2 Személyre szabás egyéni callbackkel A szofisztikáltabb integrációt a Springtab egy egyedileg definiált callbackel történik meg. Az abban megadott funkcó egyetlen paramétert kap, ez pedig nem más, mint a klaszter azonosítója. A callback definiálása a kövektezőképpen történik: <script>
//... _springtab.push(['spt_callback', function(clusterid) { //saját JavaScript kódunkat itt adhatjuk meg }]); //... Ezt a kódot a springtab integrációs kódrészletben kell elhelyezni, ahol a _springtab objektum már létezik, de az aszinkron script beillesztés még nem történt meg (a 3.2-es példa mutat erre kódot). A callback hívás a klaszter azonosító megérkezése után történik meg, ha ez az onready előtt lenne, akkor a callback újból meghívódik az onready eseménykor is. Így tehát célszerő a callbackben ellenőrizni, hogy az első hívás történik-e vagy sem. A callback definiálásával a 2.1-ben leírt működés kikapcsolásra került, természetesen a callbackend belül ugyanez a működés definiálható, például ezzel a függvénnyel: function clusterdomhide(clusterid) { var trdoms = document.getelementsbyclassname("springtab") for (var i = 0; i < trdoms.length; i++) { if (trdoms[i].classname.indexof("spt_" + clusterid) == -1) { trdoms[i].parentnode.removechild(trdoms[i]); } } } 3. Integrációs segédlet A következőkben pár egyszerűbb integrációt mutatunk be rávilágítva a felhasználás apró finomságaira. A források minden esetben egyszerűsítettek, éppen ezért nem W3C validáltak. 3.1 Adatkinyerés integráció Tesztoldal tartalma integráció előtt: <html> <head> </head> <body> Lorem ipsum </body> </html> Egyszerű Facebook cliens oldali script integrálás Facebook loginnal:
<html> <head> </head> <body> <script> window.fbasyncinit = function() { FB.init({ appid : '390420111133206', xfbml : true, }; version : 'v2.2' (function(d, s, id){ var js, fjs = d.getelementsbytagname(s)[0]; if (d.getelementbyid(id)) {return;} js = d.createelement(s); js.id = id; js.src = "//connect.facebook.net/en_us/sdk.js"; fjs.parentnode.insertbefore(js, fjs); }(document, 'script', 'facebook-jssdk')); function fblogin(){ FB.login(function(response) {},{ scope: 'email,user_friends,publish_actions,user_likes,user_relationships,user_location' } Lorem ipsum <a onclick="fblogin()">facebook login</a> </body> </html> Ezt a kódot már kiegészíthetjük a Springtab integrációval egy egyszerű copy-paste segítségével. <html> <head> <script type="text/javascript"> var _springtab=_springtab []; (function(){var a=document.createelement("script");a.type="text/javascript";a.async=!0;a.src="//js.s pringtab.com/t1.js";var b=document.getelementsbytagname("script")[0];b.parentnode.insertbefore(a,b)})(); </head> <body> <script> window.fbasyncinit = function() { FB.init({ appid : '390420111133206',
xfbml : true, version : 'v2.2' }; (function(d, s, id){ var js, fjs = d.getelementsbytagname(s)[0]; if (d.getelementbyid(id)) {return;} js = d.createelement(s); js.id = id; js.src = "//connect.facebook.net/en_us/sdk.js"; fjs.parentnode.insertbefore(js, fjs); }(document, 'script', 'facebook-jssdk')); function fblogin(){ FB.login(function(response) {},{ scope: 'email,user_friends,publish_actions,user_likes,user_relationships,user_location' } Lorem ipsum <a onclick="fblogin()">facebook login</a> </body> </html> 3.2 Teszt callback definiálása A 3.1-ben leírt integrációból az egyszerűség kedvéért kivesszük most a FB-hoz tartozó részeket, és csak a Springtab integrációt tartjuk meg. Így a kiinduló kódunk így néz ki: <html> <head> <script type="text/javascript"> var _springtab=_springtab []; (function(){var a=document.createelement("script");a.type="text/javascript";a.async=!0;a.src="//js.s pringtab.com/t1.js";var b=document.getelementsbytagname("script")[0];b.parentnode.insertbefore(a,b)})(); <script src="//code.jquery.com/jquery-1.11.0.min.js"> </head> <body> <div id="maincontent">lorem ipsum</div> </body> </html> Az egyszerűség kedvéért jquery segítségével végezzük el a dom manipulációt, a #maincontent divben fogjuk a klaszter számát elhelyezni. A kiegészített kód:
<html> <head> <script type="text/javascript"> var _springtab=_springtab []; _springtab.push(['spt_callback', function(clusterid) { jquery(function(){ $("#maincontent").text("te a "+clusterid+". klaszterbe tartozol"); }]); (function(){var a=document.createelement("script");a.type="text/javascript";a.async=!0;a.src="//js.s pringtab.com/t1.js";var b=document.getelementsbytagname("script")[0];b.parentnode.insertbefore(a,b)})(); <script src="//code.jquery.com/jquery-1.11.0.min.js"> </head> <body> <div id="maincontent">lorem ipsum</div> </body> </html>