Útmutató az integrációhoz

Átírás

1 Útmutató az integrációhoz

2 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 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:

3 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 résznél meg kell adni egy létező 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 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:

4 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 : ' ', 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:

5 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)})();

6 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>

7 //... _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:

8 <html> <head> </head> <body> <script> window.fbasyncinit = function() { FB.init({ appid : ' ', 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: ' ,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 : ' ',

9 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: ' ,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 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:

10 <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 min.js"> </head> <body> <div id="maincontent">lorem ipsum</div> </body> </html>

11 4. Springtab beágyazott kód működése A Springtab által kiadott beágyazandó kód aszinkron módon betölt egy javascriptet az oldalba, ez a kód felelős az adatkinyerésért, callback hívásért, ha nincs callback akkor a tartalom elrejtésért. A 3.1 és 3.2-es részben definiált tesztkód kombinációja alapján mutatjuk a továbbiakban, hogy milyen időzítési esetek fordulhatnak elő a Springtab használata során. Az esetek nem folyat sorrend szerint vannak felsorolva, hanem gyakoriság alapján. Ha egy látogató valamikor már meglátogatott egy springtabbel rendelkező oldalt, akkor a rendszer egy egyedi azonosítóval látja el őt, ez a trackerid. Az adatkinyerés során minden adattípusnak egy lejárati időt definiálunk, azaz hogy meddig tekintjük az adott adatot érvényesnek. A lejárati idő után a meglévő adatot továbbra is használjuk klaszterezéshez, viszont ha lehetőség van, akkor megpróbáljuk az adatkinyerést újra elvégezni.

12 Ha már valahol engedélyezte a felhasználó az adatainak a kinyerését (és azok kellően frissek) és létező trackerid-val rendelkezik, akkor az oldal megtekintése során az aszinkron script betöltődésen túl nem történik más esemény. A képen az aszinkron javascript utolsó pár karaktere látható, ez egyértelműen megadja a felhasználó trackeridját és klaszterét. Az eredmény természetesen vizuálisan is megjelenik. Az ábrán látható felhasználó az oldalhoz tartozó alkalmazást még nem engedélyezte, de az adatai a rendszerben rendelkezésre állnak, így a klaszterszámot már vissza tudjuk küldeni. Ha egy felhasználó teljesen új a rendszerben, akkor az első lekérdezéssel együtt kap egy új trackerid-t is, valamint ilyen esetekben mindenképpen a 0. klaszterbe lesz sorolva Ha a felhasználó a login gombra kattint, akkor kis idő elteltével (maximum 5-15 másodperc) a Springtab érzékeli, hogy képes lehet adatkinyerésre, így megtörténik az adatkinyerés. Jól látható, hogy a Facebook irányba történő hívások eredményeit hogyan juttatja el a rendszer a Springtab rendszeréhez. Egy ehhez hasonló folyamat játszódik le akkor is, ha a felhasználó már egyszer engedélyezte az alkalmazást majd mindenféle interakció nélkül semmi mást nem tesz, mint ellátogat az oldalra. Az adatok frissítése természetesen csak akkor történik meg, ha az adatok már régiek vagy ismeretlenek.

13 Ha nincs szükség adatfrissítésre, akkor a folyamat értelemszerűen jelentősen rövidebb:

14 Ebben az esetben csak annyi történik meg, hogy a felhasználó FB azonosítóját a Springtab összeveti a trackerid-hez kapcsolt FB azonosítóval, hogy detektálni tudja, ha egy böngészési sessionön belül a felhasználó két eltérő FB fiókot használ. Ha valami miatt elérhetetlen a Springtab szolgáltatása, attól még az oldalak zavartalanul működnek, viszont ilyen esetben a callback értelemszerűen nem lesz meghívva: OSX Safari esetében mivel a 3rd party cookie policy nem teszi lehetővé, hogy azon keresztül kövessük a felhasználót, így a js.springtab.com/iframe oldal segítségével egy iframen belüli localstorage objektum segítségével valósítjuk meg az adattárolást: