Ruby SDK

Kaynak: sdk/ruby. Modeller ve kaynak metotları api/openapi.yaml'dan üretilir (lib/pushizo/generated/); kimlik doğrulama, yeniden deneme, idempotency, sayfalama ve webhook imza doğrulaması el yazımıdır. Çalışma zamanı bağımlılığı yoktur.

KurulumBağlantıyı kopyala

# Gemfile
gem "pushizo"

KullanımBağlantıyı kopyala

require "pushizo"

hs = Pushizo::Client.new(api_key: ENV.fetch("HS_API_KEY"), app_id: "app_…") # yerelde base_url: "http://localhost:4000"

# Bildirim gönder: Idempotency-Key verilmezse otomatik UUID
res = hs.notifications.create(
  {
    target: { include_aliases: { external_id: ["user-42"] } },
    contents: { en: "Your order shipped", tr: "Siparişiniz kargoya verildi" }
  },
  idempotency_key: "order-1001"
)
puts res.id, res.status

# Kullanıcı oluştur/güncelle (Hash veya model nesnesi kabul edilir)
hs.users.upsert(Pushizo::Models::UpsertUserDto.new(external_id: "user-42", tags: { plan: "pro" }))

# Cursor sayfalama: Enumerator, sayfalar tembel yüklenir
hs.segments.list_all(limit: 100).each { |segment| puts segment.name }

# Başka bir app için tek çağrı
hs.apps.get(app_id: "app_diger")

# SDK identity verification
identity_hash = Pushizo.identity_hash(ENV.fetch("HS_SDK_SECRET"), "user-42")

Yanıtlar Pushizo::Models::* nesneleridir: alanlara snake_case metotla (msg.status) ya da msg["status"] ile erişilir, to_h JSON adlarıyla ham hash döner. Kaynaklar hs.notifications, hs.users, hs.aliases, hs.subscriptions, hs.events, hs.channels, hs.segments, hs.templates, hs.campaigns, hs.journeys, hs.in_app_messages, hs.inbox, hs.categories, hs.preferences, hs.suppressions, hs.webhooks, hs.analytics, hs.exports, hs.imports, hs.api_keys, hs.apps, hs.organization. Object#send ile çakışmaması için events.send → send_events, campaigns.send → send_campaign olarak adlandırılmıştır. A/B kazananı: campaigns.select_winner, in_app_messages.select_winner (in_app_messages.winner eski addır, kullanımdan kaldırılmıştır). SDK'da metodu olmayan uçlar ya da JSON dışı yanıtlar için hs.request(:get, "/v1/apps/{appId}/analytics/messages", query: { format: "csv" }).

AyarlarBağlantıyı kopyala

Her çağrı request_options: { timeout: 5, max_retries: 0, headers: { … } } ile ayrıca ayarlanabilir.

HatalarBağlantıyı kopyala

Kalıcı hatalar Pushizo::Error alt sınıflarıdır: status, code, request_id, details.

begin
  hs.notifications.get("msg_yok")
rescue Pushizo::NotFoundError
  # 404
rescue Pushizo::InvalidRequestError => e
  # 400/422 — e.code == Pushizo::ErrorCode::NO_RECIPIENTS
rescue Pushizo::Error => e
  # AuthenticationError, PermissionDeniedError, ConflictError, RateLimitError, ServerError, NetworkError
  warn "#{e.status} #{e.code} #{e.message}"
end

Yeniden deneme politikasıBağlantıyı kopyala

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

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_events(body, request_options: { idempotency_key: "evt-#{id}" }). Yeniden denemelerde aynı anahtar gönderilir; API aynı anahtarla 24 saat içinde gelen tekrarı ilk yanıtla karşılar.

Webhook imza doğrulamasıBağlantıyı kopyala

# Rails
class PushizoWebhooksController < ActionController::API
  def create
    events = Pushizo::Webhook.construct_events(
      request.raw_post,                               # ham gövde
      request.headers["Pushizo-Signature"],
      ENV.fetch("HS_WEBHOOK_SECRET")                  # rotasyonda [eski, yeni] verilebilir
    )
    events.each { |event| } # tekil veya batch; event["id"] ile tekrarları ayıklayın
    head :no_content
  rescue Pushizo::WebhookSignatureError => e
    render plain: e.reason, status: :bad_request
  end
end

Zaman damgası 5 dakikadan eskiyse (tolerance:) istek replay sayılır. Yalnızca doğrulama için Pushizo::Webhook.verify_signature(...) ok?, timestamp, reason döner. Olay türleri: Webhook'lar.

GeliştirmeBağlantıyı kopyala

rake test                                                # sdk/ruby içinde
node sdk/scripts/generate-server-sdks.mjs --lang ruby    # depo kökünde; generated/ yenilenir