Pushizo Docs
SDK rehberleri

Java SDK

io.pushizo:pushizo-java — Java 17+, java.net.http ve Jackson; üretilen modeller, parametre sınıfları ve kaynaklar; yeniden deneme, idempotency, sayfalama, webhook imza doğrulaması.

Kaynak: sdk/java. Modeller (io.pushizo.models), parametre sınıfları (io.pushizo.params) ve kaynaklar (io.pushizo.resources) api/openapi.yaml'dan üretilir; kimlik doğrulama, yeniden deneme, idempotency, sayfalama ve webhook imza doğrulaması el yazımıdır.

Kurulum

<dependency>
  <groupId>io.pushizo</groupId>
  <artifactId>pushizo-java</artifactId>
  <version>0.1.0</version>
</dependency>
implementation("io.pushizo:pushizo-java:0.1.0")

Kullanım

import io.pushizo.Pushizo;
import io.pushizo.RequestOptions;
import io.pushizo.models.*;
import io.pushizo.params.SegmentsListParams;
import java.util.List;
import java.util.Map;

Pushizo hs = Pushizo.builder()
        .apiKey(System.getenv("HS_API_KEY"))
        .appId("app_…")
        // .baseUrl("http://localhost:4000")
        .build();

// Bildirim gönder: Idempotency-Key verilmezse otomatik UUID
CreateNotificationResult res = hs.notifications().create(
        new CreateNotificationDto()
                .target(new CreateNotificationDtoTarget().includeAliases(Map.of("external_id", List.of("user-42"))))
                .contents(Map.of("en", "Your order shipped", "tr", "Siparişiniz kargoya verildi")),
        RequestOptions.builder().idempotencyKey("order-1001").build());
System.out.println(res.getId() + " " + res.getStatus());

// Kullanıcı oluştur/güncelle
hs.users().upsert(new UpsertUserDto().externalId("user-42").tags(Map.of("plan", "pro")));

// Cursor sayfalama: sayfalar tembel yüklenir
for (Segment segment : hs.segments().listAll(new SegmentsListParams().limit(100L))) {
    System.out.println(segment.getName());
}

// Başka bir app için tek çağrı
hs.apps().get(RequestOptions.forApp("app_diger"));

// SDK identity verification
String identityHash = Pushizo.identityHash(System.getenv("HS_SDK_SECRET"), "user-42");

Model alanları akıcı ayarlayıcılar (.contents(...)) ve getX() okuyucularıyla kullanılır; null alanlar gönderilmez, bilinmeyen alanlar yok sayılır. Kaynaklar hs.notifications(), hs.users(), hs.aliases(), hs.subscriptions(), hs.events(), hs.channels(), hs.segments(), hs.templates(), hs.campaigns(), hs.journeys(), hs.inAppMessages(), hs.inbox(), hs.categories(), hs.preferences(), hs.suppressions(), hs.webhooks(), hs.analytics(), hs.exports(), hs.imports(), hs.apiKeys(), hs.apps(), hs.organization(). A/B kazananı: hs.campaigns().selectWinner(…), hs.inAppMessages().selectWinner(…) (inAppMessages().winner(…) eski addır, @Deprecated). SDK'da metodu olmayan uçlar ya da JSON dışı yanıtlar için hs.request("GET", "/v1/apps/{appId}/analytics/messages", Map.of("format", "csv"), null, null) (gövde metin döner).

Ayarlar

BuilderVarsayılanAçıklama
apiKey—hs_live_… API anahtarı (Bearer)
appId—Çağrıda RequestOptions.appId verilmezse kullanılan app
baseUrlhttps://api.pushizo.comAPI adresi
timeout30 snDeneme başına zaman aşımı
maxRetries3En fazla yeniden deneme (politika)
autoIdempotencyKeytrueIdempotency-Key destekleyen çağrılarda otomatik UUID
transportJdkHttpTransportÖzel taşıma (ör. new JdkHttpTransport(özelHttpClient))

Çağrı başına: RequestOptions.builder().appId(..).idempotencyKey(..).timeout(..).maxRetries(..).header(..).

Hatalar

Kalıcı hatalar PushizoException (unchecked) alt sınıflarıdır: getStatus(), getCode(), getRequestId(), getDetails().

try {
    hs.notifications().get("msg_yok");
} catch (NotFoundException e) {
    // 404
} catch (InvalidRequestException e) {
    if (ErrorCodes.NO_RECIPIENTS.equals(e.getCode())) { /* 422 */ }
} catch (PushizoException e) {
    // AuthenticationException, PermissionDeniedException, ConflictException, RateLimitException, ServerException, NetworkException
}

Yeniden deneme politikası

Yeniden denemeler üstel geri çekilmeyle (0,3 / 1 / 3 sn; Retry-After başlığı varsa ona uyulur) en fazla maxRetries kez yapılır. Sunucuda tekrarlanması güvenli olmayan isteklerin çift işlenmemesi için kural HTTP metoduna göre değişir:

DurumGET, HEAD, OPTIONS, PUT, DELETEPOST, PATCH
429Yeniden denenirYeniden denenir (istek işlenmeden reddedilmiştir)
5xx, zaman aşımı, gönderim sonrası bağlantı kopmasıYeniden denenirYalnızca Idempotency-Key varsa
İstek hiç gönderilemedi (ConnectException, UnknownHostException, HttpConnectTimeoutException, NoRouteToHostException)Yeniden denenirYeniden denenir
Diğer 4xxDenenmezDenenmez

5xx ya da gönderim sonrası ağ hatasında sunucu isteği işlemiş olabilir; anahtarsız bir POST/PATCH tekrarı çift bildirim veya kayıt üretebilir. notifications().create ve users().upsert anahtar verilmezse otomatik UUID üretir (otomatik anahtar kapatılmadıysa), bu yüzden bu iki çağrı güvenle yeniden denenir. Başka bir POST/PATCH çağrısının da yeniden denenmesini istiyorsanız anahtarı kendiniz verin: hs.events().send(body, RequestOptions.builder().idempotencyKey("evt-" + id).build()). Yeniden denemelerde aynı anahtar gönderilir; API aynı anahtarla 24 saat içinde gelen tekrarı ilk yanıtla karşılar.

Webhook imza doğrulaması

import io.pushizo.WebhookEvent;
import io.pushizo.WebhookSignatureException;
import io.pushizo.Webhooks;

byte[] payload = request.getInputStream().readAllBytes();              // ham gövde
try {
    List<WebhookEvent> events = Webhooks.constructEvents(payload,
            request.getHeader(Webhooks.SIGNATURE_HEADER),
            List.of(System.getenv("HS_WEBHOOK_SECRET")));                // rotasyonda eski + yeni secret
    for (WebhookEvent event : events) {                                  // tekil veya batch gövde
        // event.getId() ile tekrarları ayıklayın; event.getType(), event.getData()
    }
    response.setStatus(204);
} catch (WebhookSignatureException e) {
    response.setStatus(400);                                             // e.getReason()
}

Yalnızca doğrulama için Webhooks.verifySignature(...) WebhookVerifyResult(ok, timestamp, reason) döner. Olay türleri: Webhook'lar.

Geliştirme

mvn test                                                 # sdk/java içinde
node sdk/scripts/generate-server-sdks.mjs --lang java    # depo kökünde; üretilmiş sınıflar yenilenir

Go SDK

github.com/exec0de/pushizo/sdk/go — Go 1.23+, yalnızca standart kütüphane; üretilen modeller ve servisler, yeniden deneme, idempotency, range-over-func sayfalama, webhook imza doğrulaması.

.NET SDK

Pushizo (NuGet) — .NET 8, HttpClient ve System.Text.Json; üretilen modeller ve kaynaklar, yeniden deneme, idempotency, IAsyncEnumerable sayfalama, webhook imza doğrulaması.

Bu sayfada

KurulumKullanımAyarlarHatalarYeniden deneme politikasıWebhook imza doğrulamasıGeliştirme