Ú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 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 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_
-t. Például: …
…
…
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: Lorem ipsum Egyszerű Facebook cliens oldali script integrálás Facebook loginnal:
<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 Facebook login Ezt a kódot már kiegészíthetjük a Springtab integrációval egy egyszerű copy-paste segítségével. <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> 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 Facebook login
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: <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"> Lorem ipsum
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:
<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"> Lorem ipsum
