diff --git a/docs/Chat AI/Android Guide.md b/docs/Chat AI/Android Guide.md deleted file mode 100644 index 3fc558e72..000000000 --- a/docs/Chat AI/Android Guide.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -pagination_next: Chat AI/Reference -pagination_prev: Chat AI/iOS Guide ---- - -# Android Guide - -This page covers how to integrate **Rezolve Commerce Brain** in your Android app using the **Point SDK**. You’ll learn about the key classes, how to create and manage chat AI sessions, and how to handle real-time responses. - -### Prerequisites - -- **Android API level 26+** -- The Rezolve AI integration is already configured in your project - -### Creating a Chat Session - -After you’ve set up the Point SDK, you can create new chat sessions at any point by accessing `BrainAI` through `ServiceManager`: - -```kotlin -val brainAI = ServiceManager.getInstance(context).brainAI -val chat = brainAI?.createNewChat() - -``` - -Every chat session has a unique `sessionID` in URN format (e.g., `urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d`). - -If you need to retrieve an existing session: - -```kotlin -val existingChat = brainAI?.getChatWithSessionID("urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d") -``` - -And when you’re done: - -```kotlin -brainAI?.closeChatWithSessionID("urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d") -``` - -### Sending Messages & Receiving Streaming Responses - -With a `Chat` object, you can send messages to **Rezolve Commerce Brain** and receive chunks of responses as they’re generated. The response stream is represented by `StreamingResponseDto` objects. - -#### Kotlin - -A coroutine-based approach is recommended for asynchronous operations, preventing blocking the main thread. - -```kotlin -// Use an appropriate coroutine scope (e.g., viewModelScope or a custom scope) -launch(Dispatchers.IO) { - try { - val responseStream = chat?.sendMessage("Tell me about the latest deals") - responseStream?.forEach { chunk -> - // Each chunk in the partial response - println("Chunk received: ${chunk.response}") - } - } catch (e: Exception) { - // Handle network or streaming errors - println("Error: ${e.localizedMessage}") - } -} - -``` - -#### Java - -If you’re using Java, you can handle the response stream using either Java 8+ streams or a callback-based approach: - -```java -try { - // Potentially run on a background thread - Stream streamOfResponses = - (Stream) chat.sendMessage("Tell me about the latest deals", new CustomContinuation>()); - - streamOfResponses.forEach(responseChunk -> { - System.out.println("Chunk received: " + responseChunk.getResponse()); - }); - -} catch (Exception e) { - // Handle errors - e.printStackTrace(); -} - -``` - -If you prefer callbacks, you can define a custom interface that’s invoked each time a new chunk of data arrives, similar to the closure approach on iOS. - -### Best Practices - -- **Session Persistence**: Keep the same `Chat` session for a single conversation flow to maintain context. -- **Error Handling**: Network or streaming errors can occur. -- **User Experience**: Consider updating your UI as chunks arrive for a more dynamic and responsive experience. \ No newline at end of file diff --git a/docs/Chat AI/Overview.md b/docs/Chat AI/Overview.md deleted file mode 100644 index 73c52a1b5..000000000 --- a/docs/Chat AI/Overview.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -pagination_next: Chat AI/Quick Start -pagination_prev: null ---- - -# Overview - -With the **Point SDK** already providing powerful location-based engagement, we’re extending its capabilities to include **Rezolve AI**. This new integration focuses on commerce-related interactions—like product inquiries, order updates, and on-the-go shopping assistance—by delivering real-time, streaming responses right inside your iOS or Android app. - -### Key Highlights - -- **Commerce Intelligence**: Tailored responses for product discovery, sales enablement, and customer support. -- **Seamless Chat Sessions**: Easily create, manage, and close chat sessions, preserving conversation context across multiple interactions. -- **Streaming Responses**: Deliver partial responses as they are generated, helping users get answers faster and stay engaged. -- **Platform Support**: Compatible with iOS 15+ and Android (API level 26+), building on top of your existing Point SDK setup. - -By combining location intelligence from the Point SDK with commerce-focused natural language understanding, you can offer a richer, more personalised user experience—right where and when your customers need it most. - -### Next Steps - -1. **Quickstart:** Get your app up and running quickly with our one-file integration examples for iOS and Android. -2. **iOS Guide & Android Guide:** Dive deeper into platform-specific setup, best practices, and code samples. -3. **Reference:** Explore detailed class and method documentation, including available properties and usage notes. \ No newline at end of file diff --git a/docs/Chat AI/Quick Start.md b/docs/Chat AI/Quick Start.md deleted file mode 100644 index 14133ae5b..000000000 --- a/docs/Chat AI/Quick Start.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -pagination_next: Chat AI/iOS Guide -pagination_prev: Chat AI/Overview ---- - -# Quickstart - -This guide shows you how to quickly integrate Rezolve AI into your existing Point SDK setup. By the end of this section, you’ll be able to send a message to the Rezolve AI and receive a streaming response on both iOS and Android. - -### Prerequisites - -- **Rezolve AI Account:** You must have an account to access the Rezolve Commerce Brain. To learn more or sign up, visit [Rezolve’s website](https://rezolve.com/commerce/). -- **Integration Activated in Canvas:** Ensure the Rezolve AI integration is enabled in Canvas. Check the [Rezolve AI Integration](../integrations/Rezolve%20AI.md) documentation for more details. -- **Point SDK** properly set up in your project -- **iOS 15.0+** or **Android API Level 26+** -- **Project ID** (API key) already configured in the Point SDK’s global config - -### 1. Initialise the Point SDK - -**Swift (iOS)** - -```swift -// iOS: Import the Point SDK and initialize -BDLocationManager.instance().initialize(projectID: "YourProjectID) -``` - -**Kotlin (Android)** - -```kotlin -// Import the Point SDK and initialize -ServiceManager.getInstance(context).initialize("YourProjectID") -``` - -### 2. Create a New Chat Session - -Once initialized, you can create a new chat session via the `brainAI` object. This session is where you’ll send messages and receive real-time responses. - -**Swift (iOS)** - -```swift -let chat = BDLocationManager.instance().brainAI.createNewChat() -// The chat object comes with a unique sessionID (e.g., urn:uuid:...) -``` - -**Kotlin (Android)** - -```kotlin -val brainAI = ServiceManager.getInstance(context).brainAI -val chat = brainAI?.createNewChat() -``` - -### 3. Send a Message and Receive Streaming Responses - -Messages sent to the Rezolve AI return a stream of responses. Depending on your platform, you can handle these asynchronously using Swift’s `async/await` or Kotlin coroutines. - -**Swift (iOS)** - -```swift -do { - let stream = try await chat.sendMessage("Tell me about my nearest store") - for try await response in stream { - // Each chunk in the response stream - print("Received chunk: \(response.response)") - } -} catch { - // Handle errors -} -``` - -**Kotlin (Android)** - -```kotlin -launch(Dispatchers.IO) { - try { - chat?.sendMessage("Tell me about my nearest store")?.forEach { chunk -> - println("Received chunk: ${chunk.response}") - } - } catch (e: Exception) { - // Handle errors - } -} -``` - -### Next Steps - -- **iOS Guide:** Explore session management details, alternative callback patterns, and best practices. -- **Android Guide:** Delve into coroutines, Java support, and deeper integration examples. -- **Reference:** See the complete set of classes (e.g., `BrainAI`, `Chat`, `StreamingResponseDto`) and their properties. \ No newline at end of file diff --git a/docs/Chat AI/Reference.md b/docs/Chat AI/Reference.md deleted file mode 100644 index 80e5412f0..000000000 --- a/docs/Chat AI/Reference.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -pagination_next: null ---- - -# Reference - -### BrainAI - -Manages chat sessions with **Rezolve AI**. Lives as a property on either `BDLocationManager` (iOS) or `ServiceManager` (Android). - -**iOS** - -```swift -let brainAI = BDLocationManager.instance.brainAI -``` - -**Android** - -```kotlin -val brainAI = ServiceManager.getInstance(context).brainAI -``` - -**Public Methods** - -| Method | Description | -| --- | --- | -| `createNewChat()` | Creates a new `Chat` session and returns the object. | -| `getChatWithSessionID(sessionID: ...)` | Retrieves an existing `Chat` session by its unique identifier. | -| `closeChatWithSessionID(sessionID: ...)` | Closes (removes) a given `Chat` session to free resources. | - -### Chat - -Represents a single chat session. Responsible for sending messages and receiving real-time (streaming) responses. - -**Public Methods** - -| Method | Platform | Description | -| --- | --- | --- | -| `sendMessage(message: String)` | iOS | Sends a message; returns an `AsyncThrowingStream`. A closure-based version is also available for earlier iOS versions. | -| `sendMessage(message: String)` | Android | Sends a message in Android; returns a `Sequence` (Kotlin) or `Stream` (Java) of `StreamingResponseDto`. | - -**Public Properties** - -| Property | Type | Description | -| --- | --- | --- | -| `sessionID` | String | Unique session identifier (e.g., `urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d`). | -| `userID` | String | Defaults to an installation reference. Useful for tracking which user initiated the chat. | -| `language` | String | Defaults to `"English"`. Set this to customise the language context for your queries. | - -### StreamingResponseDto - -A wrapper for each partial chunk of the chat’s streaming response. - -**Public Properties** - -| Property | Type | Description | -| --- | --- | --- | -| `response` | String | The text content of the current response chunk. | -| `responseID` | String | Unique identifier for the response chunk (if needed). | -| `contexts` | Array of `BDStreamingResponseDtoContext` (Android) or `ChatContext` (iOS) | List of additional context objects. | -| `streamType` | Integer | Indicates the type of stream chunk ( `1` = `CONTEXT`, `2` = `RESPONSE_TEXT`, `3` = `RESPONSE_IDENTIFIER`). | - -### Contexts in `StreamingResponseDto` - -A critical feature of **Rezolve AI** is its ability to return **contextual** product information alongside the text response. This is especially useful when building digital shopping experiences, allowing the model to reference specific items, categories, or merchants in real time. - -### iOS: `ChatContext` - -When you receive a context chunk on iOS, you’ll typically deal with an array of `ChatContext` objects. Each object provides details about a product or item that matches the user’s query. -**** - -**Public Properties** - -| Property | Type | Description | -| --- | --- | --- | -| **title** | `String` | Product or suggestion title. | -| **imageLinks** | `[URL]` | List of product/category image URLs. | -| **price** | `NSNumber` | Price of the product. | -| **contextDescription** | `String` | A descriptive text for the product or suggestion. | -| **merchantID** | `NSNumber` | Merchant identifier. | -| **categoryID** | `NSNumber` | Category identifier. | -| **productID** | `NSNumber` | Product identifier, which you can link to your backend. | - -#### Android: `BDStreamingResponseDtoContext` - -On Android, context chunks are represented by `BDStreamingResponseDtoContext` objects. - -**Public Properties** - -| Property | Type | Description | -| --- | --- | --- | -| **title** | `String` | Product or suggestion title, if available. | -| **image_links** | `Array` | List of image URLs related to the product or category. | -| **price** | `Double` | Product price. | -| **description** | `String` | Text describing the product or suggestion. | -| **merchant_id** | `Int` | Merchant identifier. | -| **category_id** | `Int` | Category identifier. | -| **product_id** | `Int` | Product identifier for linking to your database or backend systems. | - -#### How Contexts Are Used - -1. **Product Listing or Recommendations** - If the AI determines the user is asking about a product or category, it can return one or more **Context** entries, each describing an item that matches the user’s query. - -2. **Dynamic UI Updates** - Use the context data to display product cards, images, prices, and other attributes in real time. For instance, you might show a carousel of recommended items based on the user’s latest question. - -3. **Cross-Referencing** - The `merchant_id`, `category_id`, and `product_id` fields can tie back into your app’s internal product catalog. This way, when a user selects a product from the AI’s suggestion, you can seamlessly transition to a product details page or add it to a shopping cart. \ No newline at end of file diff --git a/docs/Chat AI/iOS Guide.md b/docs/Chat AI/iOS Guide.md deleted file mode 100644 index 5887e2719..000000000 --- a/docs/Chat AI/iOS Guide.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -pagination_next: Chat AI/Android Guide -pagination_prev: Chat AI/Quick Start ---- - -# iOS Guide - -This page walks you through integrating **Rezolve Commerce Brain** with your iOS app and covers creating chat AI sessions, and handling real-time responses. - -### Prerequisites - -- **iOS 15.0+** -- The Rezolve AI integration is already configured in your project - -## Creating a Chat Session - -You can create a new chat session at any time through the `brainAI` instance on `BDLocationManager`: - -```swift -// Grab the BrainAI instance from BDLocationManager -let brainAI = BDLocationManager.instance.brainAI - -// Create a new chat session -let chat = brainAI.createNewChat() - -``` - -Each session has a unique `sessionID` in URN format (e.g., `urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d`). - -If you need to reference an existing session: - -```swift -let existingChat = brainAI.getChatWithSessionID("urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d") - -``` - -When you’re done with a session, you can close it to free up resources: - -```swift -brainAI.closeChatWithSessionID("urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d") - -``` - -### Sending Messages & Receiving Streaming Responses - -Once you have a `Chat` object, you can send messages to **Rezolve Commerce Brain**. The responses arrive as a stream of **StreamingResponseDto** objects, each representing a partial chunk of the final answer. - -#### Option 1: Swift Concurrency (async/await) - -Best for projects targeting iOS 15.0 or later: - -```swift -do { - let responseStream = try await chat.sendMessage("What promotions are available today?") - - // responseStream is an AsyncThrowingStream - for try await chunk in responseStream { - // Each chunk is a partial response - print("Chunk received: \(chunk.response)") - } -} catch { - // Handle any network or streaming errors - print("Error: \(error.localizedDescription)") -} - -``` - -#### Option 2: Closures - -If your deployment target is below iOS 15 or you prefer a closure-based approach: - -```swift -chat.sendMessage("Any recommended products?", completion: { streamingResponseDto, error in - if let error = error { - print("Error: \(error.localizedDescription)") - return - } - - if let dto = streamingResponseDto { - print("Chunk received: \(dto.response)") - } -}) - -``` - -### Best Practices - -- **Reuse Chat Sessions**: Keep a single chat session open for an ongoing conversation to maintain context. -- **Error Handling**: Watch for network errors or timeouts during streaming. -- **User Experience**: Consider displaying responses in real time as chunks arrive for a more engaging conversation flow. \ No newline at end of file diff --git a/docs/Point SDK/iOS/Overview.md b/docs/Point SDK/iOS/Overview.md index 39641ea1c..cce8ed428 100644 --- a/docs/Point SDK/iOS/Overview.md +++ b/docs/Point SDK/iOS/Overview.md @@ -13,6 +13,7 @@ The following pages provide a guide to integrating the Point SDK with your iOS a * [Quick Start Guide](./Quick%20Start.md) * [Geo-triggering](./Geo-triggering.md) * [Tempo](./Tempo.md) +* [Push Notifications](./Push%20Notifications.md) * [Location Permission best practices](./Location%20Permission%20Best%20Practices.md) * [Guide to Submitting App With Location Services](../../Implementation%20and%20Best%20Practices%20Guides/Submitting%20apps%20with%20location%20services%20guide.md) * [SDK Features](./Features/App%20restart%20notification.md) diff --git a/docs/Point SDK/iOS/Push Notifications.md b/docs/Point SDK/iOS/Push Notifications.md new file mode 100644 index 000000000..4814fb5fa --- /dev/null +++ b/docs/Point SDK/iOS/Push Notifications.md @@ -0,0 +1,241 @@ +Push Notifications +================== + +Point SDK can process push notifications triggered by Rezolve campaigns. + +Prerequisites: + +* Point SDK is initialized in your app. +* Push Notifications capability is enabled for your app target in Xcode. +* A valid `aps-environment` entitlement is included in the app provisioning profile. + +To enable push notifications, complete the following steps: + +1. Configure iOS push credentials in Canvas +2. Request notification permission in the application +3. Register the device push token with the SDK +4. Forward push notification events to the SDK +5. Handle SDK callbacks when notifications are received or clicked + +Configure APNs Credentials +-------------------------- + +Before push notifications can be delivered to your application, your Apple Push Notification Service (APNs) credentials must be configured in **Canvas**. + +Navigate to: + +Project Settings -> Push Notification Settings -> iOS (APNs) + +Upload the required Apple Push credentials. + +Use the Canvas Push Notification Settings screen (iOS (APNs) tab) to confirm the iOS credential set is selected before saving. + +![Canvas Push Notification Settings for iOS (APNs)](../../assets/push-notification-settings-ios-apns.png) + +_Canvas Push Notification Settings screen with the iOS (APNs) tab selected._ + +### Required fields + +| Field | Description | +| --- | --- | +| **Signing key (.p8)** | Upload the APNs authentication key downloaded from the Apple Developer portal | +| **Team ID** | Your Apple Developer Team ID | +| **Bundle ID** | The bundle identifier of your iOS application | +| **Key ID** | The Key ID associated with your APNs authentication key | + +Once saved, Rezolve uses these credentials to deliver push notifications to your application. + +Request Notification Permission +------------------------------- + +The application must request notification permission from the user. + +```swift +UNUserNotificationCenter.current().requestAuthorization( + options: [.alert, .sound, .badge] +) { granted, error in + guard error == nil, granted else { + // Handle permission error/denial + return + } + + DispatchQueue.main.async { + UIApplication.shared.registerForRemoteNotifications() + } +} +``` + +Register for Remote Notifications +--------------------------------- + +After permission is granted, register the application for remote notifications. + +```swift +UIApplication.shared.registerForRemoteNotifications() +``` + +Configure the notification center delegate during application startup. + +```swift +func application( + _ application: UIApplication, + didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? +) -> Bool { + + UNUserNotificationCenter.current().delegate = self + + return true +} +``` + +Register Push Token with Point SDK +---------------------------------- + +When the system provides a device token, forward it to the SDK. + +```swift +func application(_ application: UIApplication, + didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { + + BDLocationManager.instance()?.pushNotifications.register(deviceToken: deviceToken) +} +``` + +If push registration fails, you may optionally notify the SDK. + +```swift +func application(_ application: UIApplication, + didFailToRegisterForRemoteNotificationsWithError error: Error) { + + BDLocationManager.instance()?.pushNotifications.registrationFailed(error) +} +``` + +Forward Push Notifications to the SDK +------------------------------------- + +When a push notification is received, forward the event to the SDK so it can process Rezolve notifications. + +### Notification received (foreground) + +```swift +func userNotificationCenter( + _ center: UNUserNotificationCenter, + willPresent notification: UNNotification +) async -> UNNotificationPresentationOptions { + + let handled = BDLocationManager.instance()? + .pushNotifications + .handleForeground(notification) ?? false + + return handled ? [.banner, .sound] : [] +} +``` + +### Notification clicked + +```swift +func userNotificationCenter( + _ center: UNUserNotificationCenter, + didReceive response: UNNotificationResponse, + withCompletionHandler completionHandler: @escaping () -> Void +) { + + BDLocationManager.instance()?.pushNotifications.handleResponse(response) + completionHandler() +} +``` + +Receive SDK Callbacks +--------------------- + +The SDK exposes callbacks when a Rezolve push notification is received or clicked. + +```swift +BDLocationManager.instance()?.pushNotifications.onNotificationReceived = { payload in + print("Rezolve push notification received") +} + +BDLocationManager.instance()?.pushNotifications.onNotificationClicked = { payload in + print("Rezolve push notification clicked") +} +``` + +These callbacks can be used to update the UI, trigger navigation, or perform application logic. + +Complete Example +---------------- + +```swift +class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate { + + func application( + _ application: UIApplication, + didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? + ) -> Bool { + + UNUserNotificationCenter.current().delegate = self + + UNUserNotificationCenter.current().requestAuthorization( + options: [.alert, .sound, .badge] + ) { granted, error in + guard error == nil, granted else { return } + DispatchQueue.main.async { + UIApplication.shared.registerForRemoteNotifications() + } + } + + BDLocationManager.instance()?.pushNotifications.onNotificationReceived = { payload in + print("Push received") + } + + BDLocationManager.instance()?.pushNotifications.onNotificationClicked = { payload in + print("Push clicked") + } + + return true + } + + func application(_ application: UIApplication, + didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { + + BDLocationManager.instance()?.pushNotifications.register(deviceToken: deviceToken) + } + + func application(_ application: UIApplication, + didFailToRegisterForRemoteNotificationsWithError error: Error) { + + BDLocationManager.instance()?.pushNotifications.registrationFailed(error) + } + + func userNotificationCenter( + _ center: UNUserNotificationCenter, + willPresent notification: UNNotification + ) async -> UNNotificationPresentationOptions { + + let handled = BDLocationManager.instance()? + .pushNotifications + .handleForeground(notification) ?? false + + return handled ? [.banner, .sound] : [] + } + + func userNotificationCenter( + _ center: UNUserNotificationCenter, + didReceive response: UNNotificationResponse, + withCompletionHandler completionHandler: @escaping () -> Void + ) { + + BDLocationManager.instance()?.pushNotifications.handleResponse(response) + completionHandler() + } +} +``` + +Integration Notes +----------------- + +* Point SDK does not request notification permissions automatically. +* Point SDK does not register for remote notifications automatically. +* The host application is responsible for managing push notification setup. +* The SDK processes Rezolve notifications and exposes callbacks to the application. \ No newline at end of file diff --git a/docs/assets/push-notification-settings-ios-apns.png b/docs/assets/push-notification-settings-ios-apns.png new file mode 100644 index 000000000..48eb22c02 Binary files /dev/null and b/docs/assets/push-notification-settings-ios-apns.png differ diff --git a/docs/intro.mdx b/docs/intro.mdx index 9c08b671f..66a836aca 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -91,7 +91,6 @@ Welcome to Rezolve, the platform that powers both **high-precision location serv ### For Mobile Apps - **Have native iOS/Android app?** → Start with [Point SDK](./Point%20SDK/Overview) for full location capabilities - **Using React Native or Flutter?** → Use our [Point SDK Wrappers](./Point%20SDK/Overview) for seamless integration -- **Need AI-powered customer chat?** → Add [Chat AI](./Chat%20AI/Overview) for commerce intelligence ### For Web Applications - **Building web-based experience?** → Use [Web SDK](./Web%20SDK/Overview) for browser-based location awareness diff --git a/sidebars.js b/sidebars.js index a0d0f9e74..ef31b1b77 100644 --- a/sidebars.js +++ b/sidebars.js @@ -36,11 +36,6 @@ const sidebars = { "Point SDK/Android/Quick Start", "Point SDK/Android/Geo-triggering", "Point SDK/Android/Tempo", - { - type: "doc", - label: "Chat AI", - id: "Chat AI/Android Guide" - }, { type: "category", label: "Features", @@ -74,11 +69,7 @@ const sidebars = { "Point SDK/iOS/Quick Start", "Point SDK/iOS/Geo-triggering", "Point SDK/iOS/Tempo", - { - type: "doc", - label: "Chat AI", - id: "Chat AI/iOS Guide" - }, + "Point SDK/iOS/Push Notifications", { type: "category", label: "Features", @@ -241,21 +232,6 @@ const sidebars = { "Canvas/How to authenticate with Config API", ], }, - { - type: "category", - label: "Chat AI", - link: { - type: "doc", - id: "Chat AI/Overview" - }, - items: [ - "Chat AI/Overview", - "Chat AI/Quick Start", - "Chat AI/iOS Guide", - "Chat AI/Android Guide", - "Chat AI/Reference" - ] - }, { type: "category", label: "Hello Screens",