API Kullanımı

İçindekiler


Önsöz


API altyapı olarak standart Restful API yapısını kullanmaktadır. Yani kayıt çekmek için GET Methodu, kayıt eklemek için POST methodu, Update için PUT methodu ve kayıt silmek için DELETE methodu kullanılır. Kayıt çekerken tek istekte maksimum 100 adet kayıt getirilebilir. Kayıt eklerken ya da güncellerken ise tek istekte maksimum 1000 kayıt güncellenebilir.1000 kayıttan daha fazla istek atarsanız APIden hata mesajı döner.

API Key Oluşturma

Panel üzerinde Admin Panel -> User – Company Settings -> API Key ekranından New butonuna tıklayarak API Key yaratmalısınız.

PastedGraphic-1

Name : API Key için bir isim girilir.
API Scope : API Key ile yapılabilecek işlemler buraya girilir (READ,INSERT,UPDATE)
Allowed Ips : API erişimi sağlayacak IP adresleri buraya girilir. (IP kısıtını kaldırmak için bu alana * girilebilir ancak güvenlik nedeniyle kesinlikle tavsiye etmiyoruz.)
Permissions : API Key ile erişim yetkisi verilecek modüller burada seçilir. Tüm modüllere yetki vermek için */*/* seçebilirsiniz. Sadece segment bilgilerini güncelleme işlemi yapılmak isteniyorsa Admin Panel/api/playground , Dynamic Content/segment yetkileri yeterlidir.

API Key https://api.webinstats.com/v1/__COMPANY_ID__/__API_KEY__/9/api/playground adresinden test edilebilir. Bu adreste __API_KEY__ yazan kısıma daha önce oluşturulan API Key girilmeli.

Eğer API Key bilgisi POST parametresi ile gönderilmek istenirse aşağıdaki formatta api isteği atılabilir.

URL : https://api.webinstats.com/v2/__COMPANY_ID__/api/9/api/playground
Post parametresi olarak ; api_key=”__API_KEY__” yollanır.

API ile Endpoint Ekleme

API ile kullanıcıya ait endpoint (GSM No, Email, WebPushToken, App Push Token vb.) bilgilerini ekleyebilir ya da güncelleyebilirsiniz.

Her endpoint tipi için endpointleri ayrı ayrı göndermelisiniz. Ayrıca webpush kayıtları için publickey ve token bilgilerini de göndermelisiniz. IP bilgilerini gönderebilirseniz her kullanıcı için IP bilgisinden şehir,hava durumu gibi bilgileri otomatik olarak ayarlayabiliriz.

Bir api isteğinde 1000’e kadar kayıt gönderebilirsiniz.

API ile gönderilen tüm parametreler URL Encoded olmalı. Content Type mutlaka application/x-www-form-urlencoded olmalı.

Endpoint Tipleri
——————-
0:WEBPUSH
1:SAFARI,
3:IOS,
4:ANDROID,
6:EMAIL,
7:SMS,
8:WEBHOOK

API İstek Örneği –> https://api.webinstats.com/v2/[__YOUR_COMPANY_ID__]/API/13/endpoint/endpoint/[__ENDPOINT_TYPE__]?_method=POST

Email için API POST parametre Örneği –> api_key=[__YOUR_API_KEY__]&data=[{“cookieid”:”XXX”,”cuid”:”MY_MEMBERID”,”endpoint”:”user1@example.com”,”ip”:”__USERIP__”,”approved”:”1″,”d”:{“segment1″:”Tech User”,”birthday”:”1980-12-24″}},{“cookieid”:”YYY”,”cuid”:”MY_SECOND_MEMBERID”,”endpoint”:”user2@example.com”,”ip”:”__USERIP__”,”approved”:”0″,”d”:{“segment1″:”Fashion User”,”birthday”:”1990-02-03″}}]

WebPush için POST parametre örneği –> api_key=[__YOUR_API_KEY__]&data=[{“cookieid”:”XXX”,”cuid”:”MY_MEMBERID”,”endpoint”:”https://fcm.googleapis.com/fcm/send/XXXX”,”publickey”:”Public Key”,”token”:”Token”,”ip”:”__USERIP__”,”approved”:”1″,”d”:{“segment1″:”Tech User”,”birthday”:”1980-12-24″}},{“cookieid”:”YYY”,”cuid”:”MY_SECOND_MEMBERID”,”endpoint”:”https://fcm.googleapis.com/fcm/send/YYYYY”,”publickey”:”Public Key”,”token”:”Token”,”ip”:”__USERIP__”,”approved”:”1″,”d”:{“segment1″:”Fashion User”,”birthday”:”1990-02-03″}}]

API playground ekranında Application olarak “Push Stats” , Module olarak “endpoint” ve Action olarak “endpoint” seçtikten sonra Help butonuna basarak endpoint gönderimi için detaylı bilgiye ulaşabilirsiniz.

API Playground URL Örneği :https://api.webinstats.com/v1/__COMPANY__ID__/__API__KEY__/9/api/playground/

Aşağıdaki bilgiler için bize ulaşabilirsiniz.
__COMPANY_ID__ –> Firmanıza ait bilginiz.
__API_KEY__ –> Kullanacağınız işlem için oluşturulan API Key bilginiz.

API Kullanımı

API playground ekranında Method=POST, Application=Dynamic Content, Module=segment, Action=segmentuser yazılıp HELP butonuna tıklandığında isteğin nasıl atılması gerektiği ile ilgili bilgiler görülür.

HELP kısmında gelen bilgileri kullanıp Playground üzerinde bilgileri ekleyerek SUBMIT’e tıklandığında API’ye gidecek istek URL’i ve dönen sonuç görülür.

Segment bilgisi güncellemek için developer ekibinin API Key ve User Info tablosundaki hash alanına ihtiyaçları olacaktır. Hash bilgisini Dynamic Content -> Definitions -> Var File -> Güncelleme yapılacak kayıt’a çift tıkla -> Advanced Tabı -> Hash alanından ulaşılabilir.

Development esnasında test yapmak için bir adet boş CSV dosyası (0 bytelık csv uzantılı bir dosya) upload edilerek testler bu dosya üzerinden yapılabilir. Daha sonra sisteminiz hazır olduğunda Segment File ID ve Hash bilgilerini değiştirip kampanyalarda kullanılacak dosyayı güncellemeye başlayabilirsiniz.

API Key değiştirilmek istendiğinde varolan API Key’in active alanı kaldırılıp yeni bir API Key oluşturulabilir.

API Segment Update Modülü

API segmentuser da sadece belirli alanları update edecek modülün kullanımında API’a yapılan istekte get parametrelerine &update_if_exists=1&keep_current_data=1 şeklinde eklemek yeterli olur. Bu sayede eski segment verilerini bozmadan sadece belirli alanları güncellemek mümkün olmaktadır.

update_if_exists=1: Eğer kullanıcı segment verileri zaten sistemde yüklü ise gönderilen değerler update edilir eğer kullanıcı verisi yoksa eklenir. Eğer bu değer 0 gönderilirse varolan kayıtları güncellenmez sadece yeni kayıtları ekler.

keep_current_data=1 : Eğer kullanıcı segment verileri zaten sistemde yüklü ise bu segment verilerini bozmadan yeni gelen değerleri ilave eder. Eğer bu değer 0 ise eski segment verilerini tamamen silerek yeni gönderilen değerleri yazar.

İlave olarak sadece spesifik bir segment alanını tablodan silmek için alanın değerini null göndermek yeterli olmaktadır. Örneğin API’a aşağıdaki şekilde bir istek atılırsa USER_119 kullanıcısı için segment4 değeri aa2 olarak ayarlanır ve segment2 değeri eğer varsa silinir. Segment verisini silmek için null değerinin tırnak içinde olmaması gerekiyor. Eğer tırnak içinde verilirse segment2 değeri string “null” şeklinde ayarlanır.

data=[{“id”:”USER_119″,”d”:{“segment4″:”aa2”,segment2:null}}]

API ile KUPON KODU EKLEME

Kupon kodu ekleme işlemi segmentuser kayıt ekleme ile aynı mantıkta yapılmaktadır. Tek fark segmentuser tablosunda bilgileri iletirken MemberID iletilmesi gerekir. Burada ise MemberID’yi boş geçerek direk olarak kupon kodu bilgisini iletilmesi yeterlidir.

Kupon kodları da segmentuser için oluşturulan dosyalar ile aynı bölümde yer almaktadır. (Dynamic Content ->Definitions -> VarFile ekranı)
Bu ekranda ilave bilgi eklenmesi istenilen kupon dosyası bulunmalıdır. İlgili dosya çift tıklanarak dosya IDsi, Advanced tabındaki Hash ve Fields kısmı kaydedilir.
Segmentuser’a veri eklerken gönderilen şekilde aynı bilgiler gönderilir. Sadece hash yerine kupon dosyasındaki hash bilgisi yazılır. ID yerine kupon kodu dosyasının IDsi yazılır ve datada MemberID iletilmemeli çünkü memberIDyi sistem duruma göre otomatik olarak atanır. Yani örnek POST data formatı şu şekilde olur : data=[{“d”:{“__KUPON_KODU_KOLON_ADI_”:”ILAVE_KUPONKODU_1″}},{“d”:{“__KUPON_KODU_KOLON_ADI_”:”ILAVE_KUPONKODU_2″}}] Bu şekilde tek istekte 1000 adete kadar ilave kupon kodu yollanabilir. Örneğin 10,000 adet kod ilave edilecekse 10 adet istekte 1000’er kupon kodu eklenebilir.
Kupon dosyalarına eklemeler bittikten sonra segmentcommit methodu 1 kez çağırılmalı. Bu method kupon dosyası ile ilgili özet bilgileri günceller. (Toplamda X adet kupon var Y adet kullanıldı vs. gibi özet bilgileri günceller.) Bu methodu upload işlemi tamamen bittikten sonra 1 kez çağırmanız yeterli olur. Her istekten sonra çağırırsanız upload hızınız yavaşlayacaktır.

API Form

API playground ekranında Application olarak WIS Form seçildiğinde Actions kısmında allforms, form ve answer isimli 3 adet servis görüntülenir. Buradan ilgili servisi seçip Submit butonuna basıldığında çağırılması gereken URL ve Result bilgisini döner. Eğer bir hata olursa da Result kısmında ilgili hatanın mesajı dönecektir.

allforms : Firma hesabında kayıtlı tüm formları getirir.
form : ID alanında yazılı olan Formun bilgilerini getirir.
answer : ID alanında yazılı olan Formun cevaplanma bilgilerini getirir.

API ile Push Gönderimi

API ile push bildirimleri, sms ve webpush gönderebilirsiniz. Bir api isteğinde 1000’e kadar kayıt gönderebilirsiniz.

API ile gönderilen tüm parametreler URL Encoded olmalı.

Onaylanmamış kullanıcıya mesaj göndermek istiyorsanız ignore_approval = 1 post parametresini kullanabilirsiniz. Bu parametreyi çok dikkatli kullanmalısınız ve bu parametreyi EMAIL veya SMS ile kullanmanızı önermiyoruz. SMS ve EMAIL gönderimlerinde transactional mesajlar (iade talebiniz alındı, kargonuz yola çıktı gibi) dışında bu parametreyi kullanmamanızı tavsiye ediyoruz. Kullanıcının SMS ve EMAIL onayı olmadan kampanya mesajı gönderdiğinizde cezai yaptırımlarla karşılaşabilirsiniz.

Push bildirimi veya SMS gönderimi planlamak istiyorsanız, delay (dakika olarak) post parametresini kullanabilirsiniz. delay = 30 ayarlarsanız, mesajlarınız 30 dakika içinde gönderilecek şekilde planlanır. DELETE (POST değil) yöntemiyle Push Stats-> send-> send yöntemini kullanarak zamanlanmış iletileri (zaten gönderilmediyse) iptal edebilirsiniz.

İletişim Türü bunlardan biri olmalıdır

0 = WEBPUSH
1 = SAFARI PUSH
3 = IOS PUSH
4 = ANDROID PUSH
6 = E-POSTA
7 = SMS

API istek Örneği –> https://api.webinstats.com/v2/[__YOUR_COMPANY_ID__]/[__YOUR_API_KEY__]/13/send/send/[__COMMUNICATION_TYPE__]

API GET Parametreleri –> _method=POST

API POST Parametreleri –> api_key=__API__KEY__&datatype=[__MUST_BE_ONE_OF_endpoint,cookieid,cuid,id__]&sid=[__PUSH_ID__]&delay=0&ignore_approval=0&data=[{“id”:”2″,”d”:{“name”:”Alex”,”pnr”:”WQ9997″}},{“id”:”3″,”d”:{“name”:”John”,”pnr”:”WQ9998″}}]

api_key = API Key bu alana kopyalanmalı
sid = PUSH Template ID bilgisi. Gönderilmek istenilen içeriğe ait push id’sini bu alana girilmeli
datatype = Member ID için cuid, Cookie ID için uid girilmelidir.
delay = Bildirimi hemen göndermek istiyorsanız bu değeri 0 olarak girmelisiniz. xx süre sonra göndermek istiyorsanız dakika cinsinden değeri girmelisiniz. Örn (delay=30 : 30 dakika sonra gönderim yapılmak üzere planlanır.)
ignore_approval = Özellikle SMS için Transactional SMSlerde kullanıcı SMS onayından çıksa dahi SMS göndermek için 1 yapılmalı
data = JSON array –> id: Member ID ve d : Değişkenler buraya aktarılmalı

API playground ekranında Application olarak “Push Stats” , Module olarak “send” ve Action olarak “send” seçtikten sonra Help butonuna basarak push gönderimi için detaylı bilgiye ulaşabilirsiniz.

API ile Push Bildirim İzinlerinin Değiştirilmesi

Push bildirim iznini server tarafından aktif etmek, pasife çekmek ya da değerini okumak için aşağıdaki adımları izlemelisiniz.

Push Bildirim İzin Durumunu Serverdan Okumak için

Method : POST
Content-type : application/x-www-form-urlencoded
API URL : https://api.webinstats.com/v2/__COMPANY_ID___/API/13/endpoint/endpoint/__SUBSCRIPTION__TYPE__?endpoint=__DEVICE__TOKEN__&_method=GET
POST Body : api_key=__API__KEY___

Playground Ekranından aşağıdaki adımları izleyerek isteği simüle edebilirsiniz.
Playground URL’inde company_id ve api_key alanlarını değiştirerek linki browserda açın
Method : GET , Application : Push Stats , Module : endpoint, Action : endpoint , id : Subscription Type , GET Params : endpoint=__DEVICE__TOKEN ,POST Params : api_key=__API__KEY__
İkinci maddedeki bilgileri girerek submite basın
Dönen cevapta IS_APPROVED parametresinin değeri 0 ise push bildirim izni yok, 1 ise izni var demektir.

Push Bildirim İzin Durumunu Kullanıcı Bazlı Serverdan Okumak için

Method : POST
Content-type : application/x-www-form-urlencoded
API URL : https://api.webinstats.com/v2/__COMPANY_ID___/API/13/endpoint/endpoint/__SUBSCRIPTION__TYPE__?cuid=__MEMBER_ID__&_method=GET
POST Body : api_key=__API__KEY___

Playground Ekranından aşağıdaki adımları izleyerek isteği simüle edebilirsiniz.
Playground URL’inde company_id ve api_key alanlarını değiştirerek linki browserda açın
Method : GET , Application : Push Stats , Module : endpoint, Action : endpoint , id : Subscription Type , GET Params : cuid=__MEMBER_ID__ ,POST Params : api_key=__API__KEY__
İkinci maddedeki bilgileri girerek submite basın
Dönen cevapta IS_APPROVED parametresinin değeri 0 ise push bildirim izni yok, 1 ise izni var demektir.

Push Bildirim İznini Serverdan Aktif Etmek için

Method : POST
Content-type : application/x-www-form-urlencoded
API URL : https://api.webinstats.com/v2/__COMPANY_ID___/API/13/endpoint/endpoint/__SUBSCRIPTION__TYPE__?endpoint=__DEVICE__TOKEN__&_method=POST
POST Body : api_key=__API__KEY___&data=[{“endpoint”:”__DEVICE_TOKEN__”,”approved”:”1″}]

Playground Ekranından aşağıdaki adımları izleyerek isteği simüle edebilirsiniz.
Playground URL’inde company_id ve api_key alanlarını değiştirerek linki browserda açın
Method : POST , Application : Push Stats , Module : endpoint, Action : endpoint , id : Subscription Type , GET Params : endpoint=__DEVICE__TOKEN ,POST Params : api_key=__API__KEY__&data=[{“endpoint”:”__DEVICE_TOKEN__”,”approved”:”1″}] İkinci maddedeki bilgileri girerek submite basın

Push Bildirim İznini Serverdan Pasife Almak için

Method : POST
Content-type : application/x-www-form-urlencoded
API URL : https://api.webinstats.com/v2/__COMPANY_ID___/API/13/endpoint/endpoint/__SUBSCRIPTION__TYPE__?endpoint=__DEVICE__TOKEN__&_method=POST
POST Body : api_key=__API__KEY___&data=[{“endpoint”:”__DEVICE_TOKEN__”,”approved”:”0″}]

Playground Ekranından aşağıdaki adımları izleyerek isteği simüle edebilirsiniz.
Playground URL’inde company_id ve api_key alanlarını değiştirerek linki browserda açın
Method : POST , Application : Push Stats , Module : endpoint, Action : endpoint , id : Subscription Type , GET Params : endpoint=__DEVICE__TOKEN ,POST Params : api_key=__API__KEY__&data=[{“endpoint”:”__DEVICE_TOKEN__”,”approved”:”0″}] İkinci maddedeki bilgileri girerek submite basın

Subscription Types →
——————-
0:WEBPUSH
1:SAFARI,
3:IOS,
4:ANDROID,
6:EMAIL,
7:SMS,
8:WEBHOOK

Playground URL : https://api.webinstats.com/v1/__COMPANY__ID__/__API__KEY__/9/api/playground/