Push Bildirimleri

Kullanıcılarınıza Web Push bildirimleri gönderin. SDK ile kurulumu yapın, geri kalanı AI halleder.

Not

Push bildirim API’leri SDK düzeyinde kısmen işlevseldir — abonelikler kaydedilir ve gönderme çağrıları hatasız tamamlanır. Ancak gerçek tarayıcı push iletimi henüz production ortamında etkin değildir: enable() tarafından döndürülen VAPID anahtarları rastgele baytlardır, geçerli P-256 EC anahtarları değildir; bu nedenle production iletimi etkinleştirilene kadar tarayıcı aboneliği (pushManager.subscribe) başarısız olacaktır. Mesajlar kayıt altına alınır ancak cihazlara push gönderilmez. Production iletimi yakında kullanıma sunulacak.

Her Proyecta uygulaması, kullanıcılarına tarayıcı ve PWA push bildirimleri gönderebilir. Proyecta SDK; VAPID anahtar üretimini, abonelik depolama, konu yönetimi ve iletimi üstlenir — herhangi bir üçüncü taraf hesabı gerekmez.

Nasıl çalışır

Proyecta’daki push bildirimleri, dört adımdan oluşan standart Web Push yaşam döngüsünü izler:

1. Enable — uygulamanız için VAPID anahtarları oluşturur (tek seferlik)
2. Subscribe — bir kullanıcının cihazını bildirim almak üzere kaydeder
3. Identify — anonim bir aboneliği oturum açmış bir kullanıcıyla ilişkilendirir
4. Send — belirli kullanıcılara, konulara veya herkese bildirim iletir

Bu dört adımın tamamı SDK’daki proyecta.pushNotifications altında yer alır.

Uygulamanız için push’u etkinleştirin

İlk çağrı, tarayıcının bir abonelik oluşturması için ihtiyaç duyduğu VAPID genel anahtarını üretir. Bu işlem idempotent’tir — tekrar çağrıldığında aynı anahtar döner.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

const { vapidPublicKey } = await proyecta.pushNotifications.enable();

AI’a şunu sorun: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Kullanıcının cihazını abone edin

İstemci tarafında VAPID anahtarıyla bir Web Push aboneliği oluşturun, ardından bunu bir visitorId ile birlikte sunucuya gönderin:

// client side
const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: PROYECTA_VAPID_PUBLIC_KEY,
});

// server side (or via your API route)
const { secret } = await proyecta.pushNotifications.subscribe({
    visitorId: currentUser?.id ?? generateAnonymousId(),
    subscription: {
        endpoint: subscription.endpoint,
        keys: {
            auth: subscription.keys.auth,
            p256dh: subscription.keys.p256dh,
        },
    },
});
// Store `secret` on the client — it's required to unsubscribe or identify later

Kullanıcı oturum açmışsa visitorId olarak kimlik doğrulanmış kullanıcı kimliğini, anonim ziyaretçiler için ise oluşturulmuş bir UUID kullanın.

Anonim abonelikleri kullanıcılarla ilişkilendirin

Anonim bir ziyaretçi oturum açtığında, bir sonraki send çağrısının onları hedefleyebilmesi için mevcut aboneliğini kimlik doğrulanmış kullanıcı kimliğiyle ilişkilendirin:

await proyecta.pushNotifications.identify({
    secret: storedSubscriptionSecret,
    userId: authenticatedUser.id,
});

Bildirim gönderin

Belirli ziyaretçi kimliklerini, konuları, her ikisini birden (birleşim olarak) hedefleyebilir ya da herkese yayın yapabilirsiniz. Yayın yapmak için hem visitorIds hem de topics parametrelerini atlayın.

// Send to specific users
await proyecta.pushNotifications.send({
    title: 'Your order has shipped',
    body: 'Track it from your dashboard',
    visitorIds: ['user_123', 'user_456'],
    data: { orderId: 'ord_789' }, // custom payload
});

// Send to everyone subscribed to a topic
await proyecta.pushNotifications.send({
    title: 'New feature just dropped',
    topics: ['product-updates'],
    icon: 'https://cdn.example.com/icon.png',
    image: 'https://cdn.example.com/banner.png',
});

// Broadcast to all subscribers
await proyecta.pushNotifications.send({
    title: 'Scheduled maintenance at 2am UTC',
});

send, { sent, failed } döndürür; böylece iletimin nasıl gittiğini görebilirsiniz. Mevcut taslak yanıttaki sent sayısı, hedeflenen kayıtlı abonelik sayısını yansıtır; gerçek tarayıcı iletimlerini değil — production iletimi etkinleştirilene kadar bunu bir iletim onayı olarak kullanmayın.

Konular

Kullanıcılar, proyecta.pushNotifications.topics alt kaynağı aracılığıyla adlandırılmış konulara abone olabilir (ör. product-updates, weekly-digest). Bu, opt-in listelerini yönetmenin önerilen yoludur — yayın tarzı güncellemeler için ziyaretçi kimliklerini kendiniz takip etmenize gerek kalmaz.

Abonelikten çıkma

subscribe’dan dönen secret’ı kullanarak bir aboneliği kaldırın:

await proyecta.pushNotifications.unsubscribe({ secret });

Her şeyi AI’a bırakın

Bunların hiçbirini elle yazmak zorunda değilsiniz. AI’a şunu sorun:

• "Enable push notifications for my app. Register a service worker, call pushNotifications.subscribe on the client after the user grants permission, and store the secret in localStorage."
• "Send a push to all users subscribed to the 'breaking-news' topic whenever a new article is published."
• "After a user signs in, call pushNotifications.identify to link their anonymous subscription to their user ID."

Dikkat edilmesi gerekenler

• Preview ortamında gerçek push gönderilmez. Push bildirimleri yalnızca uygulamanızın yayımlanmış sürümünde çalışır; çünkü tarayıcılar gerçek bir origin üzerinde HTTPS gerektirir.
• iOS’ta PWA zorunludur. iOS 16.4 ve sonrasında Web Push, doğrudan Safari’den değil yalnızca yüklenmiş bir Progressive Web App’ten (ana ekrana eklenmiş) çalışır.
• İzin tek seferlik bir fırsattır. Bir kullanıcı bildirim iznini reddederse tarayıcılar programatik olarak yeniden istemde bulunmanıza izin vermez. Kullanıcıyı tarayıcı veya cihaz ayarlarına yönlendirmeniz gerekir.

Yakında

• Zamanlanmış ve olay tetiklemeli gönderimler — uygulama olaylarına veya bir takvime göre otomatik gönderim
• Derin bağlantı (deep linking) — bildirime dokunulduğunda uygulamada belirli bir ekranı açma