Ruby SDK upgrade (v0.x to v1.0)
This guide will help you upgrade from the previous Knock Ruby SDK to the new v1.0 Ruby SDK.
Basic Changes#
Client Initialization#
New Features in v1.0#
-
Strong Typing with Sorbet: Improved type definitions for better IDE integration
-
Auto-pagination: Easily iterate through paginated resources
-
Enhanced Error Handling: More specific error classes
-
Configurable Timeouts and Retries: Fine-tune request behavior
-
New Resources: Additional resources like Audiences, Channels, and Integrations
-
Request Options: More control over individual requests
Breaking Changes#
-
Client Design: The new SDK uses an instance-based client rather than module functions
- Create a client instance with
knock = Knockapi::Client.new()
- Call methods via the client:
knock.workflows.trigger()
instead ofKnock::Workflows.trigger()
- Create a client instance with
-
Method Naming and Organization:
Knock::Users.identify()
→knock.users.update()
Knock::Users.set_preferences()
→knock.recipients.preferences.set()
Knock::Users.get_channel_data()
→knock.recipients.channel_data.get()
- Bulk operations are now organized in their own namespaces:
knock.users.bulk.*
,knock.objects.bulk.*
- The main module is now
Knockapi
instead ofKnock
-
Method Parameters: Parameters are now passed differently
- Most methods now take the ID(s) as positional parameter(s), followed by named parameters
- Resource IDs moved from named parameters to positional parameters (e.g.,
id: "user-1"
→"user-1"
) data:
parameters have been flattened in most methods
-
Preference Management:
- Preferences are now handled through the
recipients.preferences
module - The preference set ID must be explicitly provided (usually "default")
- Preferences are now handled through the
-
Response Handling:
- The new SDK returns model instances rather than raw hashes
- Pagination is handled via cursor-based pagination instead of page-based
Common Operations#
Triggering Workflows#
Old SDK:
New SDK:
Identifying Users#
Old SDK:
New SDK:
Working with Preferences#
Old SDK:
New SDK:
Support#
If you encounter any issues during migration, please reach out to our support team or open an issue on GitHub.