API

Az API, php programozási nyelvű kiegészítők készítésére alkalmas, szakszerű használatához ezen programozási nyelv ismerete feltétlenül szükséges.
Az API letölthető ha ide kattintasz.

Használatával a Webgalambban tárolt feliratkozók adataihoz férhetsz hozzá az alábbiak szerint:

Feliratkozó adatainak lekérdezése
Feliratkozó adatainak módosítása
Új feliratkozó felvitele
Feliratkozó másolása másik csoport(ok)ba
Feliratkozó törlése

Az API fájlnak nem feltétlenül szükséges a Webgalamb mappájában lennie, azonban mindenképpen el kell, hogy érje a Webgalamb által használt MySQL kiszolgálót.

Amit fontos tudni

A csoportok mindegyike saját azonosítóval rendelkezik, ami egy szám.
A feliratkozók minden feliratkozás alkalmával új feliratkozóként kerülnek rögzítésre, ezen okból ha egy cím többször is szerepel a Webgalambban, akkor mindegyik saját feliratkozói azonosítóval rendelkezik.

Kezdeti lépések

Első lépésként a Webgalamb adatbázis kapcsolatát kell felépíteni, majd meghívni a Webgalamb API-t.

1. A Webgalamb MySQL kapcsolati fájljának használatával:

// Webgalamb MySQL fájl meghívása (helyes útvonalat neked kell tudnod!)
require_once('./files/wg5conf.php');

// Webgalamb 5 API meghívása
require_once('wg5api.php');
$wg_api = new WG5_API($db_pre, $hostname_local, $database_local, $username_local, $password_local);

2. Helyileg megadott Webgalamb MySQL adatbázis adatokkal:

// Webgalambhoz használt MySQL adatbázis adatai
$db_pre = 'wg5_';              // Webgalamb 5 prefix, alap telepítés esetén => wg5_
$hostname_local = "localhost"; // adatbázis kiszolgáló címe
$database_local = "database";  // adatbázis neve
$username_local = "username";  // adatbázis felhasználónév
$password_local = "password";  // felhasználó jelszava

// Webgalamb 5 API meghívása
require_once('wg5api.php');
$wg_api = new WG5_API($db_pre, $hostname_local, $database_local, $username_local, $password_local);

Új feliratkozók lekérdezése egy megadott dátumhoz viszonyítva

// A kezdő időpont, amelyet követően feliratkozók érdekelnek.
$datetime = "2014-03-07 09:40:01";

// Csoportazonosító, ha nulla értéket adsz meg akkor minden csoportra érvényes.
$group_id = 0;

// 
$result = $wg_api->GetNewSubscribers($datetime, $group_id);

// Eredmény kiírása, feldolgozása.
print_r($result);

Az eredményként kapott tömb az új feliratkozók Webgalambos azonosítóját (kulcs) és csoportok nevét (érték) tartalmazza.

Minta eredmény:

Array
(
    [335] => minta@mintakft.hu
    [336] => example@example.com
    [337] => example2@example.com
)

Módosult adatokkal rendelkező feliratkozók lekérdezése egy megadott dátumhoz viszonyítva

// A kezdő időpont, amelyet követően feliratkozók érdekelnek.
$datetime = "2014-03-07 09:30:01";

// Csoportazonosító, ha nem adsz meg értéket akkor minden csoportra érvényes.
$group_id = false; 

//
$result = $wg_api->GetUpdatedSubscribers($datetime, $group_id);

// Eredmény kiírása, feldolgozása.
print_r($result);

Az eredményként kapott tömb az új feliratkozók Webgalambos azonosítóját (kulcs) és csoportok nevét (érték) tartalmazza.

Minta eredmény:

Array
(
    [122] => minta3@mintakft.hu
    [337] => example3@example.com
)

Egy adott csoporthoz tartozó feliratkozók azonosítóinak lekérdezése

// Csoportazonosító megadása.
$group_id = 1;

//
$result = $wg_api->GetGroupUserIDs($group_id);

// Eredmény kiírása, feldolgozása.
print_r($result);

Az eredményként kapott tömb az új feliratkozók Webgalambos azonosítóját (érték) tartalmazza.

Minta eredmény:

Array
(
    [0] => 337
    [1] => 276
    [2] => 275
    [3] => 277
    [4] => 278
    [5] => 279
)

Adott e-mail címhez tartozó Webgalambos azonosítók lekérése

// Feliratkozói e-mail cím.
$subscriber_mail = 'teszt@webgalamb.hu';

//
$result = $wg_api->GetUserIDs($subscriber_mail);

// Eredmény kiírása, feldolgozása.
print_r($result);

Az eredményként kapott tömb a megadott e-mail cím összes előfordulásának azonosítóját (érték) tartalmazza.

Minta eredmény:

Array
(
    [0] => 275
    [0] => 645
    [0] => 1244
)

Feliratkozó adatainak lekérése

Ha e-mail cím alapján kérsz le adatokat, akkor az összes ezen címhez tartozó feliratkozó adatát megkapod, csoporttól függetlenül. Az adataiban azonban szerepel a csoportazonosító is amelyhez tartozik, így könnyen be lehet azonosítani.

Ha a feliratkozó azonosítójával kérdezed le az adatokat, akkor a konkrét feliratkozó adatait kapod meg.

// Feliratkozó rögzített e-mail címe (egyszerű változó)
$subscriber_eid = 'example2@example.com'; 

// Feliratkozó Webgalambos azonosítója (tömb)
$subscriber_eid = array(337, 654); 

//
$result = $wg_api->GetSubscriber($subscriber_eid);

// Eredmény kiírása, feldolgozása.
print_r($result);

Az eredményként kapott tömb a megadott e-mail címhez vagy Webgalambos azonosítóhoz tartozó összes előfordulásának adatait tartalmazza.

Minta eredmény:

Array
(
    [0] => Array
        (
            [mail] => example@example.com
            [mail_id] => 9
            [nmail] => 
            [omail] => 
            [ip] => 11.22.33.44
            [datum] => 2013-03-10
            [ipdatum] => 2014-10-30 13:36:55
            [mdatum] => 2014-10-31 08:38:34
            [verify_code] => kaka96265ke71bf86777bkb1k45b5ad93ef7e5e6
            [active] => 1
            [g] => 1
            [a] => 1
            [bounce] => 0
            [am] => 0
            [id] => 337
            [Feliratkozási URL] => 
            [Név] => Teszt Elek
        )
    [1] => Array
        (
            [mail] => example@example.com
            [mail_id] => 9
            [nmail] => 
            [omail] => 
            [ip] => 55.66.77.88
            [datum] => 2014-07-22
            [ipdatum] => 2014-10-30 13:36:55
            [mdatum] => 2014-10-31 08:38:34
            [verify_code] => kaka962s5ke71bf86777bkb1k45b5ad93ef7e5e6
            [active] => 1
            [g] => 2
            [a] => 1
            [bounce] => 0
            [am] => 0
            [id] => 654
            [Feliratkozási URL] => 
            [Név] => Teszt Elek
        )
)

Csoportok lekérdezése

$result = $wg_api->GetGroups();

// Eredmény kiírása, feldolgozása.
print_r($result);

Az eredményül kapott tömb a csoportok Webgalambos azonosítóját (kulcs) és csoportok nevét (érték) tartalmazza.

Minta eredmény:

Array
(
    [1] => Csoport 1
    [12] => Csoport 2
    [32] => Csoport 3
)

Új feliratkozó felvitele

A rögzítendő adatok az e-mail címet lászámítva opcionálisak, megadásuk nem kötelező.

// Rögzítendő adatok.
$subscriber_data = array (
			// E-mail cím 
			'mail' => 'example2@example.com',	

			// Feliratkozási dátum, ha nincs megadva akkor az aktuális dátum kerül be.
			'datum' => '2013-03-10',	

			// Státusz: 1 -> aktív, 0 -> inaktív, 2 -> visszapattant
			// Ha nincs megadva akkor aktív státusszal kerül be
			'active' => 1,             			
			
			'Név' => 'Minta János',
			'Telefonszám' => '06-70/123-4567',
			'Cégnév' => 'Minta Kft.'
	 );

// A feliratkozási csoport csoportazonosítója.
$group_id = 1; 

//
$result = $wg_api->InsertSubscriber($subscriber_data, $group_id);

// Eredmény kiírása, feldolgozása.
echo $result;

Sikeres rögzítés esetén a Webgalambos azonosítóval tér vissza.
ha -1 a visszatérő érték akkor nem sikerült a felvitel, már van ilyen e-mail cím a csoportban,
ha -2 a visszatérő érték akkor pedig nem létező csoportba próbáltál feliratkoztatni,
ha -3 a visszatérő érték akkor hibás az e-mail cím.

Feliratkozó adatainak módosítása

// módosítandó adatok
$subscriber_data = array (
					'Telefonszám' => '06-1/123-4567',
					'Név' => 'Teszt Elek'
	 ); 

// Feliratkozó rögzített e-mail címe vagy Webgalambos azonosítója
$subscriber_eid = 'example@example.com';

// Csoportazonosító (kötelező)
$group_id = 1;

//
$result = $wg_api->EditSubscriber($subscriber_data, $subscriber_eid, $group_id); 

// Eredmény kiírása, feldolgozása.
if($result > 0) {
    echo "Sikeres adatmódosítás";
} elseif($result == -2) {
    echo "Hiba: nem létező csoport";
} elseif($result == -3) {
    echo "Hiba: nem létező feliratkozó";
}

Visszatérési érték:
1 -> sikerült az adatmódosítás
-2 -> nem létező csoportot adtál meg,
-3 -> nem létező feliratkozót akartál módosítani.

Feliratkozó másolása

// Feliratkozó Webgalambos azonosítója
$subscriber_id = 325;

// A célcsoport(ok) azonosítói (legalább 1 kötelező!)
$target_groups = array(2, 3);

//
$result = $wg_api->CopySubscriber($subscriber_id, $target_groups);

// Eredmény kiírása, feldolgozása.
print_r($result);

A visszatérési érték egy tömb a sikeres másolás adataival, ahol a kulcs a csoportazonosítót az érték pedig az adott csoportba történő másolás eredményét tartalmazza.
Alapból minden érték az újonnan létrejött feliratkozó adott csoportban használt Webgalambos azonosítóját jelzi.
ha -1 az érték akkor nem sikerült a felvitel, már van ilyen e-mail cím a csoportban,
ha -2 akkor pedig nem létező csoportba próbáltál feliratkoztatni,
ha -3 hibás e-mail cím.

Minta eredmény:

Array
(
    [2] => -3
    [3] => 624
)

Feliratkozó(k) törlése

// Feliratkozó rögzített e-mail címe vagy Webgalambos azonosítója
$subscriber_eid = 'example@example.com'; 

// Csoportazonosító(k), ha nem adsz meg értéket akkor minden csoportra érvényes.
// Ha feliratkozó azonosításnál id-t használsz akkor ez a paraméter figyelmen kívül lesz hagyva!
$group_ids = array();

//
$result = $wg_api->DeleteSubscriber($subscriber_eid, $group_ids);

// Eredmény kiírása, feldolgozása.
print_r($result);

A visszatérési érték egy tömb a sikeres törlések adataival, ahol a kulcsok a csoportazonosítókat, az értékek pedig a feliratkozó adott csoporthoz tartozó azonosítóját tartalmazza.
Ha nincs visszatérési érték akkor nem törölt senkit, a megadott paramétereknek nem felelt meg egyik feliratkozó sem.

Minta eredmény:

Array
(
    [2] => 126
    [3] => 264
)