import { Col, DangerNote, Note, Properties, Row, WarningNote } from '../../../components/mdx'
import { Tag } from '../../../components/Tag'
import { TimelineContainer } from '../../../components/TimelineContainer'
import { TimelineHeader } from '../../../components/TimelineHeader'
import { TimelineBody } from '../../../components/TimelineBody'
import { Card, CardContent, CardFooter, CardHeader, CardTitle } from '../../../components/ui/card'
import { UpBubbleIcon } from '../../../components/icons/UpBubbleIcon'
import { ThumbUpIcon } from '../../../components/icons/ThumbUpIcon'
import { EmailBubbleIcon } from '../../../components/icons/EmailBubbleIcon'
import { BentoCoinIcon } from '../../../components/icons/BentoCoinIcon'
import { SectionTitle } from '../../../components/SectionTitle'
import ClipboardButton from '../../../components/ui/ClipboardButton'
import { Code } from '../../../components/Code'
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/ui/accordion"
import { Collapsable } from '../../../components/MDXCollapsible'
import CodeSample from '../../../components/CodeSample'
import { ArrowIcon } from '../../../components/icons/ArrowIcon'
import Link from 'next/link'
import { GuideLinkCards } from '../../../components/GuideLinks'

export const exampleFile = 'ruby-guide-examples'
export const metadata = {
  title: 'Ruby SDK Guide',
  description:
    "Today, we'll explore integrating the Ruby on Rails SDK from Bento.",
}



# Bento Ruby Guide

This guide will help you implement Bento into your Ruby on Rails applications, regardless of your development experience.

<div className="grid grid-cols-1 sm:grid-cols-2 gap-x-4 gap-y-2">
  <GuideLinkCards
    icon={UpBubbleIcon}
    title="Getting Started"
    links={[
      { label: 'Installation', href: '#installation' },
      { label: 'Basic Setup', href: '#basic-setup' },
    ]}
  />

  <GuideLinkCards
    icon={ThumbUpIcon}
    title="Beginner Guide"
    links={[
      { label: 'Tracking Your First Event', href: '#tracking-your-first-event' },
      { label: 'Managing Subscribers', href: '#managing-subscribers' },
      { label: 'Common Use Cases', href: '#common-use-cases' },
    ]}
  />

  <GuideLinkCards
    icon={EmailBubbleIcon}
    title="Intermediate Guide"
    links={[
      { label: 'Tracking Purchase Events', href: '#tracking-purchase-events' },
      { label: 'Namespaced Tags', href: '#using-custom-fields-and-tags' },
    ]}
  />

  <GuideLinkCards
    icon={BentoCoinIcon}
    title="Advanced Guide"
    links={[
      { label: 'Batch Operations', href: '#batch-operations' },
      { label: 'Transactional Emails', href: '#transactional-emails' },
      { label: 'Subscriber Updates', href: '#subscriber-updates' },
      { label: 'Utility Features', href: '#utility-features' },
    ]}
  />
</div>

### Reference
<div className={'flex flex-col gap-y-1 mb-8'}>
  <div><span className={'text-xl text-violet-500'}>#</span> [API Reference](#api-reference)</div>
  <div><span className={'text-xl text-violet-500'}>#</span> [Troubleshooting](#troubleshooting)</div>
  <div><span className={'text-xl text-violet-500'}>#</span> [FAQ](#faq)</div>
</div>

<SectionTitle title={'Getting Started'}/>

<div>
  <TimelineContainer>
    <TimelineHeader title={'Package Installation'} number={'1'}/>
    <TimelineBody>
      ## Installation

      Install the Bento Go SDK in your project:

      <CodeSample exampleFile={exampleFile} exampleKey="install_npm"  />
    </TimelineBody>

    <TimelineHeader title={'Client Configuration'} number={'2'}/>
    <TimelineBody>
      ## Basic Setup

      To initialize the Bento client, you'll need your Site UUID, Publishable Key, and Secret Key from your Bento account.
      You can find your keys in your [Bento Team](https://app.bentonow.com/account/teams). To see your keys click
      `Your Private API Keys` Button and if do you do not see a Publishable key and Secret Key, click on `Generate Key` to
      create a set.

      <CodeSample exampleFile={exampleFile} exampleKey="basic_setup"  />
    </TimelineBody>
  </TimelineContainer>
</div>

<SectionTitle title={'Beginner Guide'}/>

## Tracking Your First Event

Events represent specific actions users take within your application. Tracking these actions provides valuable insights
into user behavior patterns and engagement.

#### Streamlined Subscriber Management
We recommend using Events as the preferred method to add subscribers, as they simultaneously initiate workflows and
automations in a single operation.

#### Powerful Data Enrichment
Events excel at capturing contextual information alongside user actions. This can be used in emails via
[liquid tags](/liquid_guide) or in segmentation. For instance, when recording a purchase event, you can include detailed
transaction information such as:

| Detail                                                                        | Liquid tag                                                                                                                                         |
|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| <span className="text-violet-400">Product details</span> | <ClipboardButton isColored={true} textToCopy='{{ event.details.product.size }}' defaultLabel="{{ event.details.product.size }}" />                 |
| <span className="text-violet-400">Purchase amount</span> | <ClipboardButton isColored={true} textToCopy='{{ event.details.value.amount }}' defaultLabel="{{ event.details.value.amount }}" />                 |
| <span className="text-violet-400">Transaction ID</span>  | <ClipboardButton isColored={true} textToCopy='{{ event.details.value.amount }}' defaultLabel="{{ event.details.value.amount }}" />                 |
| <span className="text-violet-400">Payment method</span>  | <ClipboardButton isColored={true} textToCopy='{{ event.details.value.payment_method }}' defaultLabel="{{ event.details.value.payment_method }}" /> |

### Practical Example
When a customer completes a purchase, you can track this as an event while including all relevant purchase details. This
approach enables you to:

- Trigger specific post-purchase workflows
- Launch targeted follow-up automations
- Track lifetime value (LTV) metrics
- Create personalized communications based on purchase history


<CodeSample exampleFile={exampleFile} exampleKey="simple_page_view"  />

<CodeSample exampleFile={exampleFile} exampleKey="track_form_submission"  />

## Managing Subscribers

If you need to manage subscribers directly there are a set of convenience methods available to you. Add, update, and
unsubscribe subscribers with these simple methods. Currently, you cannot remove subscribers via the API, but you can
remove them from the dashboard `People > All Users`.

<Collapsable defaultOpen={false} openLabel="2 More Samples">
  <summary>
    <CodeSample exampleFile={exampleFile} exampleKey="create_a_new_subscriber"  />
  </summary>
  <content>

    <CodeSample exampleFile={exampleFile} exampleKey="tag_a_subscriber"  />
    <CodeSample exampleFile={exampleFile} exampleKey="unsubscribe_a_subscriber"  />
  </content>
</Collapsable>



#### Adding Individual Subscribers
Please note, while these methods make it easy to manage a subscriber, the Bento recommended way to add **a** subscriber
is via an `event`. This allows you to kick off sequences and automations, while also recording the "event" at the same
time (1 API call).

#### Adding Multiple Subscribers
Importing or modifying multiple subscribers should be handled via the [bulk methods](/examples/nodejs#subscriber-updates),
instead of looping over these calls multiple times.


## Common Use Cases

Here are some common scenarios with ready-to-use code:
<Collapsable defaultOpen={false} openLabel="2 More Samples">
  <summary>
    <CodeSample exampleFile={exampleFile} exampleKey="tracking_user_login_event"  />
  </summary>
  <content>
    <CodeSample exampleFile={exampleFile} exampleKey="updaing_user_information"  />
    <CodeSample exampleFile={exampleFile} exampleKey="adding_multiple_tags_to_a_subscriber"  />
  </content>
</Collapsable>

<SectionTitle title={'Intermediate Guide'}/>

## Tracking Purchase Events

When recording purchase events, you must include a `unique:` key as part of the tracking data. This requirement prevents
duplicate transactions from being recorded in your analytics.

Most users find it beneficial to use their internal cart or order number as the `unique:` key. This approach simplifies
future lookups and maintains consistency across your systems. The `unique:` key value you provide is accessible through
liquid tags when creating custom email templates, allowing for personalized transactional messaging based on specific
purchase details.

Tracking purchases is a great way to monitor customer lifetime value (LTV) and identify recurring customers. Bento reports
on the LTV of each subscriber, allowing you to identify high-value customers and tailor your marketing efforts accordingly.

<CodeSample exampleFile={exampleFile} exampleKey="tracking_purchase_events"  />

<SectionTitle title={'Advanced Guide'}/>

## Batch Operations

For efficiency, we suggest using batch operations when integrating with Bento. These methods allow for single or bulk
operations on subscribers and events, improving the performance and scalability of your integration. They also cover more
than 80% of the API use cases for most customers.

<CodeSample exampleFile={exampleFile} exampleKey="import_multiple_subscribers"  />
<CodeSample exampleFile={exampleFile} exampleKey="import_multiple_events"  />


## Transactional Emails

Bento allows you to send personalized transactional emails for time-sensitive, direct communications. These emails serve
specific functional purposes rather than marketing objectives.

<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
  <div className=" ">
    #### Ideal Transactional Email Use Cases
    * User onboarding (confirmation etc)
    * Password reset notifications
    * Sign-in verification links
    * Order confirmations and details
    * Account notifications
  </div>

  <div className="md:bg-neutral-900 rounded-lg md:pl-4">
    #### NOT Ideal Transactional Email Use Cases
    * CC / BCC recipients
    * Emails that require an attachment (we suggest always using links for emails for best deliverability)
    * Marketing of any kind
    * Promotional content
    * Newsletters
  </div>
</div>

#### From Address Requirements
The sender address used in your transactional emails must be configured as an Author email within your Bento settings.
Please note that generic addresses such as "~[no-reply@domain.com](mailto:no-reply@domain.com)~" or similar non-personal
addresses are not currently supported.

#### Important Distinction
**Transactional** emails are designed for **essential communications** that facilitate specific **user actions** or provide
critical information.

<DangerNote>Transactional emails should **not** be used as substitutes for **marketing** campaigns or **promotional**
  content.</DangerNote>


<CodeSample exampleFile={exampleFile} exampleKey="send_transactional_emails"  />

## Subscriber Updates

Many organizations joining Bento already have an established subscriber base that requires bulk updates over time. These
updates commonly include setting field data and managing tags across multiple subscribers. We firmly believe that these
methods are the best way to manage a single or multiple subscribers, and we recommend using them for all subscriber
updates.

<Note>These methods cover more than 80% of the API use cases for most customers.</Note>

#### Choosing the Right Update Method:


The SDK offers multiple approaches for creating subscribers in Bento, each suited to different scenarios.

#### Preferred Method: Events

The recommended way to create subscribers is via events in response to user activity. This approach activates
automations, workflows, and can contain data enrichment.

<Collapsable defaultOpen={false} openLabel="1 More Sample">
  <summary>
    <CodeSample exampleFile={exampleFile} exampleKey="create_a_subscriber_when_they_sign_up"  />
  </summary>
  <content>
    <CodeSample exampleFile={exampleFile} exampleKey="create_a_subscriber_when_they_make_a_purchase"  />
  </content>
</Collapsable>

#### Alternative Methods

For scenarios where you need to create subscribers independently of user actions:
<TimelineContainer>
  <TimelineHeader title={'Single Subscriber Creation'} number={'1'} />
  <TimelineBody>
    Use this method when you need to quickly create a single subscriber with minimal data:

    <CodeSample exampleFile={exampleFile} exampleKey="create_a_single_subscriber"  />

    <WarningNote> This endpoint is rate-limited and not suitable for loops or bulk creation. Use only for individual subscriber creation.</WarningNote>

  </TimelineBody>
  <TimelineHeader title={'Multiple Or Enriched Subscriber Creation'} number={'2'} />
  <TimelineBody>
    For creating multiple subscribers or including additional fields:

    <CodeSample exampleFile={exampleFile} exampleKey="import_multiple_subscribers_at_once"  />

    Best Practices for Batch Imports:
    * Though the API supports up to 1,000 subscribers per call, we recommend batches of 200-300 for optimal performance when dealing with extensive data.
    * Include all relevant custom fields in the initial import to minimize follow-up updates.
    * For very large imports (10,000+ subscribers), consider implementing a queue system with delay between batches.

  </TimelineBody>
</TimelineContainer>

#### Updating Subscribers
Depending on your requirements, several approaches are available for updating subscriber information.

#### Event-Based Updates (Preferred)
When updates occur in response to user actions, tracking events is the recommended approach:

<CodeSample exampleFile={exampleFile} exampleKey="update_subscriber_when_they_update_their_profile"  />

<Note>Becuase you can apply as many changes via automations / workflows as you want this is the most flexible method.
  It doesn't require code or deployment changes, and can be completely handled in Bento. </Note>

#### Alternative Update Methods

For updates outside of user-triggered actions:
<TimelineContainer>
  <TimelineHeader title="Single Attribute Updates" number={'1'}/>
  <TimelineBody>
    For quickly updating a specific attribute on a single subscriber:
    <Collapsable defaultOpen={false} openLabel="2 More Samples">
      <summary>
        <CodeSample exampleFile={exampleFile} exampleKey="add_or_update_a_single_field"  />
      </summary>
      <content>
        <CodeSample exampleFile={exampleFile} exampleKey="add_a_tag"  />
        <CodeSample exampleFile={exampleFile} exampleKey="remove_a_field"  />
      </content>
    </Collapsable>

    <WarningNote>The Command API is not recommended for multiple updates or bulk operations. Given its heavy rate limit, use the Batch API instead.</WarningNote>
  </TimelineBody>
  <TimelineHeader title="Batch Updates" number={'2'}/>
  <TimelineBody>
    For updating multiple subscribers or multiple fields at once, use the batch import method:

    <CodeSample exampleFile={exampleFile} exampleKey="update_multiple_subscribers"  />

    Recommendations:
    * Even for single-subscriber updates, consider using the batch import method when multiple fields need updating.
    * The batch import performs an "upsert" operation – it creates subscribers that don't exist and updates those that do.
    * This approach provides the most flexibility as your use cases evolve, whether you need to add more changes or modify multiple users simultaneously.

  </TimelineBody>
</TimelineContainer>

#### Specialized Update Operations
For specific update scenarios, the SDK offers dedicated methods:

<Collapsable defaultOpen={false} openLabel="2 More Samples">
  <summary>
    <CodeSample exampleFile={exampleFile} exampleKey="change_a_subscribers_email_address"  />
  </summary>
  <content>

    <CodeSample exampleFile={exampleFile} exampleKey="update_all_fields_at_once"  />
    <CodeSample exampleFile={exampleFile} exampleKey="unsubscribe_a_user"  />
  </content>
</Collapsable>

## Utility Features

These features provide additional convenience utility for Bento users, to handle some of the common secondary use cases
we commonly see, such as validation and blacklist checks.

<CodeSample exampleFile={exampleFile} exampleKey="validate_email"  />

<SectionTitle title={'API Reference'}/>

### Core API

- **Client** - Main entry point for using the SDK (`Bento::`)
- **Configuration** - Set up through the `Bento::Configurationg` with API keys and settings
- **Error Handling** - Error handling via standard `StandardError`
- **Battle Tested** - SDK is in active use by Bento for all our api needs

### Convenience Methods


#### Core API

| Use Case                                                                         | Ruby SDK Method                                                                                                                                                                                                                      |
|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <span className="text-violet-400">Add a new subscriber</span>                    | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.find_or_create_by(email: "user@example.com")' defaultLabel="Bento::Subscribers.find_or_create_by(email: email)" />                                                  |
| <span className="text-violet-400">Unsubscribe a subscriber </span>               | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.unsubscribe(email: "user@example.com")' defaultLabel="Bento::Subscribers.unsubscribe(email: email)" />                                                              |
| <span className="text-violet-400">Update data for an existing subscriber </span> | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.import([{email: "user@example.com", fields: {}}])' defaultLabel="Bento::Subscribers.import(subscribers)" />                                                         |
| <span className="text-violet-400">Add a tag to a subscriber </span>              | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.add_tag(email: "user@example.com", tag: "tag_name")' defaultLabel="Bento::Subscribers.add_tag(email: email, tag: tag)" />                                           |
| <span className="text-violet-400">Update subscriber fields </span>               | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.add_field(email: "user@example.com", key: "field_name", value: "field_value")' defaultLabel="Bento::Subscribers.add_field(email: email, key: key, value: value)" /> |
| <span className="text-violet-400">Track a custom event </span>                   | <ClipboardButton isColored={true} textToCopy='Bento::Events.track(email: "user@example.com", type: "event_type")' defaultLabel="Bento::Events.track(email: email, type: type)" />                                                    |
| <span className="text-violet-400">Track a purchase event </span>                 | <ClipboardButton isColored={true} textToCopy='Bento::Events.track(email: "user@example.com", type: "$purchase", details: {})' defaultLabel="Bento::Events.track(email: email, type: '$purchase', details: details)" />               |

### Modules

#### Batch
| Use Case                                                              | Method                                                                                                                                         | API Reference                                                                                                                                         |
|-----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| <span className="text-violet-400">Import multiple subscribers </span> | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.import(subscribers)' defaultLabel="Bento::Subscribers.import(subscribers)" /> | <Link href="/subscribers#import-subscribers" className="inline-flex items-center gap-1">Import Subscribers <ArrowIcon className={'h-6 w-6'} /></Link> |
| <span className="text-violet-400">Import multiple events </span>      | <ClipboardButton isColored={true} textToCopy='Bento::Events.import(events)' defaultLabel="Bento::Events.import(events)" />                     | <Link href="/events_api#create-events" className="inline-flex items-center gap-1">Import Events <ArrowIcon className={'h-6 w-6'} /></Link>            |
| <span className="text-violet-400">Send emails </span>                 | <ClipboardButton isColored={true} textToCopy='Bento::Emails.send_bulk(emails)' defaultLabel="Bento::Emails.send_bulk(emails)" />               | <Link href="/emails_api#create-emails" className="inline-flex items-center gap-1">Send Emails <ArrowIcon className={'h-6 w-6'} /></Link>              |

#### Commands
| Use Case                                                       | Method                                                                                                                                                                                                                                   | API Reference                                                                                                                                        |
|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| <span className="text-violet-400">Add a tag </span>            | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.add_tag(email: "user@example.com", tag: "tag_name")' defaultLabel="Bento::Subscribers.add_tag(email: email, tag: tag)" />                                               | <Link href="/subscribers#import-subscribers" className="inline-flex items-center gap-1">Subscriber Upsert <ArrowIcon className={'h-6 w-6'} /></Link> |
| <span className="text-violet-400">Remove a tag </span>         | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.remove_tag(email: "user@example.com", tag: "tag_name")' defaultLabel="Bento::Subscribers.remove_tag(email: email, tag: tag)" />                                         | <Link href="/subscribers#import-subscribers" className="inline-flex items-center gap-1">Subscriber Upsert <ArrowIcon className={'h-6 w-6'} /></Link> |
| <span className="text-violet-400">Add a field </span>          | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.add_field(email: "user@example.com", key: "field_name", value: "field_value")' defaultLabel="Bento::Subscribers.add_field(email: email, key: key, value: value)" />     | <Link href="/subscribers#import-subscribers" className="inline-flex items-center gap-1">Subscriber Upsert <ArrowIcon className={'h-6 w-6'} /></Link> |
| <span className="text-violet-400">Remove a field </span>       | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.remove_field(email: "user@example.com", field: "field_name")' defaultLabel="Bento::Subscribers.remove_field(email: email, field: field)" />                             | <Link href="/subscribers#import-subscribers" className="inline-flex items-center gap-1">Subscriber Upsert <ArrowIcon className={'h-6 w-6'} /></Link> |
| <span className="text-violet-400">Subscribe a user </span>     | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.subscribe(email: "user@example.com")' defaultLabel="Bento::Subscribers.subscribe(email: email)" />                                                                      | <Link href="/subscribers#run-command" className="inline-flex items-center gap-1">Subscriber Command <ArrowIcon className={'h-6 w-6'} /></Link>       |
| <span className="text-violet-400">Unsubscribe a user </span>   | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.unsubscribe(email: "user@example.com")' defaultLabel="Bento::Subscribers.unsubscribe(email: email)" />                                                                  | <Link href="/subscribers#run-command" className="inline-flex items-center gap-1">Subscriber Command <ArrowIcon className={'h-6 w-6'} /></Link>       |
| <span className="text-violet-400">Change email address </span> | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.change_email(old_email: "old@example.com", new_email: "new@example.com")' defaultLabel="Bento::Subscribers.change_email(old_email: old_email, new_email: new_email)" /> | <Link href="/subscribers#run-command" className="inline-flex items-center gap-1">Subscriber Command <ArrowIcon className={'h-6 w-6'} /></Link>       |

#### Experimental
| Use Case                                                         | Method                                                                                                               | API Reference                                                                                                                                                       |
|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <span className="text-violet-400">Validate email address </span> | <ClipboardButton isColored={true} textToCopy='Bento::Spam.valid?(email)' defaultLabel="Bento::Spam.valid?(email)" /> | <Link href="/utility#validate-email" className="inline-flex items-center gap-1">Validate Email <ArrowIcon className={'h-6 w-6'} /></Link>                           |
| <span className="text-violet-400">Check risky email </span>      | <ClipboardButton isColored={true} textToCopy='Bento::Spam.risky?(email)' defaultLabel="Bento::Spam.risky?(email)" /> | <Link href="/utility#validate-email-against-jesses-ruleset" className="inline-flex items-center gap-1">Check Risky Email <ArrowIcon className={'h-6 w-6'} /></Link> |


#### Subscribers
| Use Case                                                      | Method                                                                                                                                                                              | API Reference                                                                                                                                     |
|---------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| <span className="text-violet-400">Find subscriber </span>     | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.find_or_create_by(email: "user@example.com")' defaultLabel="Bento::Subscribers.find_or_create_by(email: email)" /> | <Link href="/subscribers#find-subscriber" className="inline-flex items-center gap-1">Find Subscriber <ArrowIcon className={'h-6 w-6'} /></Link>   |
| <span className="text-violet-400">Create a subscriber </span> | <ClipboardButton isColored={true} textToCopy='Bento::Subscribers.find_or_create_by(email: "user@example.com")' defaultLabel="Bento::Subscribers.find_or_create_by(email: email)" /> | <Link href="/subscribers#find-subscriber" className="inline-flex items-center gap-1">Create Subscriber <ArrowIcon className={'h-6 w-6'} /></Link> |

<SectionTitle title={'Troubleshooting'}/>

#### Common Errors

|                                                            |                                                                   |
|------------------------------------------------------------|-------------------------------------------------------------------|
| <Tag color={'rose'} variant={'large'}>Not Authorized</Tag> | Check your API keys and ensure they have appropriate permissions  |
| <Tag color={'rose'} variant={'large'}>Rate Limited</Tag>   | Implement backoff/retry logic for batch operations                |
| <Tag color={'rose'} variant={'large'}>Network Errors</Tag> | Check internet connectivity and API endpoint availability         |
| <Tag color={'rose'} variant={'large'}>Exceptions</Tag>     | Double check you are using a valid `Author` & the payload format. |



#### Debugging Tips

|    |                                                                           |
|----|---------------------------------------------------------------------------|
| 1. | Enable `logErrors: true` in your configuration for detailed error logging |
| 2. | Use try/catch blocks around API calls to handle errors gracefully         |
| 3. | For batch operations, start with smaller batches to isolate issues        |


<SectionTitle title={'FAQ'}/>

<Accordion type="single" collapsible>


  <AccordionItem value="item-2">
    <AccordionTrigger>How do I handle rate limiting?</AccordionTrigger>
    <AccordionContent>
      Implement exponential backoff with Ruby's retry patterns when you encounter rate limit responses. You can use
      `retriable` or implement your own retry logic:

      <CodeSample exampleFile={exampleFile} exampleKey="rate_limiting"  />
    </AccordionContent>
  </AccordionItem>

  <AccordionItem value="item-3">
    <AccordionTrigger>What's the maximum batch size for importing subscribers or events?</AccordionTrigger>
    <AccordionContent>
      Up to 1,000 subscribers or events can be imported in a single batch operation. We recommend batches of 200-300 for
      optimal performance. For large imports, consider using a batching queue for parallel processing:

      <CodeSample exampleFile={exampleFile} exampleKey="max_batch_size"  />
    </AccordionContent>
  </AccordionItem>

  <AccordionItem value="item-4">
    <AccordionTrigger>How do I track anonymous users?</AccordionTrigger>
    <AccordionContent>
      Currently, the SDK requires an email address for all tracking. Anonymous tracking support is planned for future
      releases.
    </AccordionContent>
  </AccordionItem>

  <AccordionItem value="item-5">
    <AccordionTrigger>Which Ruby versions are supported?</AccordionTrigger>
    <AccordionContent>
      The SDK requires Ruby 2.6+ or higher to support the latest features and security improvements. We recommend using the latest stable version of Ruby for optimal performance and security.
    </AccordionContent>
  </AccordionItem>

  <AccordionItem value="item-6">
    <AccordionTrigger>How can I contribute to the SDK?</AccordionTrigger>
    <AccordionContent>
      We welcome contributions! Check the GitHub repository at [github.com/bentonow/bento-ruby-sdk](https://github.com/bentonow/bento-ruby-sdk)
      for contribution guidelines. You can submit pull requests, report issues, or suggest new features.
      For direct assistance, join our community Discord server.
    </AccordionContent>
  </AccordionItem>



</Accordion>