English

Pushizo Web SDK — Web push permission and subscription (VAPID), email and SMS subscriptions, users, tags and aliases, events, in-app messages, notification inbox, user preferences and the service worker. The API surface is compatible with eski sağlayıcı v5.

Status: The script tag is served by the Pushizo API today; the npm package is being published. Durum: Script etiketi bugün Pushizo API'sinden sunulur; npm paketinin yayını hazırlanıyor.

Install from GitHub until then · O zamana kadar GitHub'dan kurulum:

npm install --allow-remote=root https://github.com/pushizo/pushizo-web/releases/download/v0.1.0/pushizo-web-0.1.0.tgz

After publication · Yayından sonra:

<script src="https://api.pushizo.com/sdk-web/PushizoSDK.js" async></script>
<script>
  window.PushizoDeferred = window.PushizoDeferred || [];
  PushizoDeferred.push((Pushizo) => Pushizo.init({ appId: 'app_…' }));
</script>

npm install @pushizo/web

The detailed guide below is in Turkish; code samples are language-neutral. Full documentation: docs.pushizo.com/docs/sdk/web · API reference: docs.pushizo.com/docs/api.

Türkçe

@pushizo/web

Pushizo Web SDK: Web Push izni ve aboneliği, e-posta/SMS aboneliği, kullanıcı/tag/alias yönetimi, olaylar, in-app mesajlar, bildirim kutusu, kullanıcı tercihleri ve service worker. eski sağlayıcı v5 yüzeyiyle uyumludur.

Ayrıntılı kullanım kılavuzu: docs.pushizo.com/docs/sdk/web.

Kurulum

<script src="https://api.pushizo.com/sdk-web/PushizoSDK.js" async></script>
<script>
  window.PushizoDeferred = window.PushizoDeferred || [];
  PushizoDeferred.push(async (Pushizo) => {
    await Pushizo.init({ appId: 'app_…', apiUrl: 'https://api.pushizo.com' });
  });
</script>

import Pushizo from '@pushizo/web';
await Pushizo.init({ appId: 'app_…', apiUrl: 'https://api.pushizo.com' });

CommonJS (eski paketleyiciler, Jest): paket require koşulunda dist/cjs/index.cjs ve CommonJS tür tanımlarını sunar.

const { Pushizo } = require('@pushizo/web'); // veya require('@pushizo/web').default

Paket boyutu bütçesi size-budget.json'dadır (gzip); npm run size -w @pushizo/web derlenmiş çıktıyı denetler ve CI aşımda başarısız olur.

Site kökünde PushizoSDKWorker.js bulunmalıdır (içeriği API'deki worker'ı importScripts ile yükler).

API yüzeyi

| Alan | Üyeler | |------|--------| | Yaşam döngüsü | init, setConsentGiven, login(externalId, identityHash?), logout, destroy | | User | addTag(s), removeTag(s), getTags, setLanguage, setProperty, addAlias(es), removeAlias, addEmail, removeEmail, addSms, removeSms, getPreferences(), setPreferences([...]), getCategories(), setAdsPersonalizationConsent(bool), getConsents(), id, externalId, pushSubscription.{id, token, optedIn, state, optIn, optOut, addObserver} | | Notifications | permission, requestPermission, addClickListener, addForegroundLifecycleListener | | Slidedown | promptPush, promptEmail, promptSms, promptEmailAndSms (hepsi { force? }) | | Session | sendEvent(name, properties?, value?, { eventId? }) — eventId: tarayıcı pikseliyle aynı kimlik (Conversions API tekilleştirmesi, docs/guides/conversions-api.md) | | InAppMessages | addTrigger(s), removeTrigger(s), clearTriggers, getTriggers, setScreen, addClickListener, addLifecycleListener, paused | | Inbox | list, markRead, markAllRead, archive, unreadCount, addObserver | | CustomLink | render | | Location | setShared(bool), isShared, requestPermission(rationale?) (yalnızca ön plan; ayrıntı web rehberi "Konum") | | Attribution | get(): { first, last } (UTM / tıklama kimliği dokunuşları; aşağıdaki bölüm) |

Atribüsyon (UTM ve tıklama kimlikleri)

SDK her sayfa açılışında adresteki utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id ve reklam tıklama kimliklerini (fbclid, gclid, gbraid, wbraid, ttclid, li_fat_id, msclkid; birden çoksa bu sırayla ilki) okur ve bir dokunuş kaydeder.

await Pushizo.init({
  appId: 'app_…',
  attribution: { enabled: true, windowDays: 30, captureClickIds: true }, // varsayılanlar
});
const { first, last } = Pushizo.Attribution.get(); // ilk ve son dokunuş (yoksa null)

• enabled: false: hiçbir parametre okunmaz, saklanmaz, gönderilmez. windowDays 1–90 aralığına kırpılır; captureClickIds: false iken yalnızca UTM parametreleri dokunuş üretir.
• Saklama: çerez yazılmaz; ilk ve son dokunuş SDK'nın yerel deposunda (localStorage, hs:<appId>) tutulur ve windowDays'ten eski kayıtlar okunurken silinir. Aynı parametrelerle 30 dakika içindeki yeniden yükleme yeni dokunuş sayılmaz.
• Kişisel veri: landing_url yalnızca origin + yoldur (sorgu ve hash alınmaz); referrer yalnızca yönlendiren sitenin host'udur, sitenin kendi host'u gönderilmez.
• Rıza: requiresPrivacyConsent açıkken onay verilene kadar hiçbir şey yakalanmaz; setConsentGiven(false) atribüsyon kayıtlarını ve bekleyen dokunuşları siler.
• Gönderim: dokunuşlar çevrimdışı kuyrukla POST /sdk/v1/apps/{appId}/attribution'a gider; abonelik varsa subscription_id + sahiplik kanıtı (token_hash / identity_hash), yoksa login ile verilen external_id kullanılır. İkisi de yoksa dokunuş cihazda bekler, abonelik oluşunca veya login sonrası gönderilir. touch_id yeniden denemelerde aynı kalır (sunucu tekilleştirir).

Önerilen reklam URL parametreleri (izleme şablonu / URL parametreleri alanı):

| Platform | Parametreler | |----------|--------------| | Meta | utm_source=facebook&utm_campaign={{campaign.id}}&utm_content={{adset.id}} (fbclid otomatik eklenir) | | Google Ads | utm_source=google&utm_campaign={campaignid}&utm_content={adgroupid} (otomatik etiketleme açıkken gclid / gbraid / wbraid gelir) | | TikTok | utm_source=tiktok&utm_campaign=__CAMPAIGN_ID__&utm_content=__AID__ (ttclid otomatik eklenir) |

Tercihler, kategoriler ve diğer özellikler

Kullanıcı tercihleri

const { preferences, categories } = await Pushizo.User.getPreferences();
Pushizo.User.setPreferences([
  { category: 'promo', optedIn: false },                 // tüm kanallar
  { category: 'news', optedIn: true, channel: 'email' }, // tek kanal
]);

GET/PUT /sdk/v1/apps/{appId}/preferences; abonelik sahiplik kanıtı (token_hash, login'de identity_hash) otomatik eklenir. setPreferences çevrimdışı kuyruğa yazılır.

Reklam kişiselleştirme rızası: Pushizo.User.setAdsPersonalizationConsent(true) kullanıcının e-posta/telefon SHA-256 özetinin app'in bağladığı reklam platformu kitlelerine gönderilmesine izin verir; false geri alır (sonraki senkronda kitlelerden çıkarılır). getConsents() rıza kayıtlarını döner. Rehber: docs/guides/ad-audiences.md.

E-posta/SMS toplama istemi

await Pushizo.init({ appId: 'app_…', slidedown: { enabled: true, collect: 'email_sms' } });
await Pushizo.Slidedown.promptEmail();

collect: 'push' | 'email' | 'sms' | 'email_sms' (init ya da dashboard istemi prompt.collect). E-posta/SMS için adres alanı + kabul düğmesi; doğrulama addEmail/addSms ile aynı. Kabulde adres kaydedilir ve istem bir daha gösterilmez; ret push istemiyle aynı geri çekilme takvimine uyar. collect yoksa push davranışı değişmez.

In-app

• trigger_groups: gruplar VEYA, grup içi VE (triggers ilk grup).
• Yeni tetik session_duration { seconds }: oturum süresi eşiğe ulaşınca zamanlayıcıyla gösterilir.
• Yeni düğme aksiyonları push_prompt (yerel izin istemi) ve outcome { name, value? } (olay gönderir).
• variant_id (A/B görünüm varyantı) her gösterim/tıklama/kapatma olayıyla geri gider.
• App geneli aralık config.in_app.min_interval_seconds: herhangi bir in-app mesajın son gösteriminden beri süre dolmadan yeni mesaj gösterilmez (kalıcı).

Oturum süresi

pagehide ve zaman aşımında POST /sessions { duration_seconds } kuyruğu beklemeden keepalive fetch ile gönderilir; geçici hatada kuyruğa düşer.

Geliştirme

npm run -w sdk/web build       # dist/index.js (ESM), dist/PushizoSDK.js (IIFE), dist/PushizoSDKWorker.js
npm run -w sdk/web typecheck
npx vitest run --project unit sdk/web

Boyut bütçesi: IIFE gzip < 25 KB (~24,0 KB), service worker gzip < 5 KB (~3,9 KB).

Support · Destek

• Guide · Rehber: docs.pushizo.com/docs/sdk/web
• API reference & OpenAPI · API referansı ve OpenAPI: docs.pushizo.com/docs/api · pushizo-openapi
• Bugs & ideas · Hata ve öneri: Issues
• Security · Güvenlik: please do not open public issues; email [email protected] · herkese açık issue açmayın, bu adrese yazın.
• Help · Destek: [email protected]

This repository is mirrored automatically from the Pushizo main repository on every release. Please open an issue instead of a pull request; fixes land in the main repository and ship with the next release. Bu depo her sürümde Pushizo ana deposundan otomatik yansıtılır. Pull request yerine issue açın; düzeltmeler ana depoda yapılır ve bir sonraki sürümle buraya gelir.

Released under the MIT License · MIT lisanslıdır — LICENSE.