Recomms AI
    Recomms AI
    • Documentation
    • Recomms AI SDK
    • Items
      • Create an item
        POST
      • Update an item
        PATCH
      • Get items
        GET
      • Get item by ID
        GET
      • Delete item
        DELETE
      • Get item side info
        GET
      • Create item side info
        POST
      • Delete item side info
        DELETE
      • Reset items
        POST
    • Users
      • Create a user
        POST
      • Update a user
        PATCH
      • Get users
        GET
      • Get user by ID
        GET
      • Delete user
        DELETE
      • Get user side info
        GET
      • Create user side info
        POST
      • Delete user side info
        DELETE
      • Reset users
        POST
    • Interactions
      • Record an interaction
        POST
      • Get interactions
        GET
      • Delete an interaction
        DELETE
      • Record multiple interactions
        POST
      • Reset interactions
        POST
    • Business Rules
      • Create a new business rule
        POST
      • List business rules
        GET
      • Get business rule by ID
        GET
      • Update business rule
        PATCH
      • Delete business rule
        DELETE
    • Recommendations
      • Get item recommendations for a user
      • Get user recommendations for an item
      • Get similar users
      • Predict scores for user-item pairs
      • Predict scores for a batch of user-item combinations
      • Search for items
      • Search for users
      • Get top items

    Recomms AI SDK

    Recomms AI SDK Comprehensive Usage Guide#

    Introduction#

    The Recomms AI SDK is a powerful tool that allows you to easily integrate recommendation and interaction tracking features into your JavaScript applications. This guide will walk you through the process of setting up and using the SDK, explaining each feature and parameter in detail.

    Installation#

    To use the Recomms AI SDK in your project, include the following script tag in your HTML file:
    This will make the RecommsAISdk class available in your JavaScript code.

    Initialization#

    To start using the SDK, you need to create an instance of the RecommsAISdk class. Here's how to do it:
    Parameters:
    'your-public-key': This is a unique identifier provided by Recomms AI that authenticates your application. It's like a password for your app to access the Recomms AI services.
    'your-database-id': This is the identifier for your specific database within the Recomms AI system. It determines which set of data your application will interact with.
    Replace these placeholder values with the actual ones provided to you by Recomms AI.

    Using the SDK#

    Getting Recommendations with Pagination#

    The SDK provides methods for getting recommendations with pagination support:

    Items to User Recommendations#

    This method suggests items to a specific user.
    Parameters:
    userId (string, required): The unique identifier of the user you want recommendations for.
    pageSize (number, optional, default: 10): The number of recommendations per page.
    page (number, optional, default: 1): The page number to retrieve.
    targetItemId (string, optional): If provided, recommendations will be tailored to be similar to this item.
    scenarioId (string, optional): The identifier of a specific recommendation scenario you want to use.
    brParams (object, optional): An object containing business rule parameters. Each key is a business rule ID, and the value is what you want to set for that rule.
    itemFilters (array, optional): An array of filter objects to narrow down the recommended items. Each filter object should have field, condition, and value properties.
    itemBoosters (array, optional): An array of booster objects to influence the ranking of recommended items. Each booster object should have field, condition, value, and boost properties.
    Example:

    Searching with Pagination#

    The SDK allows you to search for items based on specific criteria with pagination support:

    Search Items#

    Parameters:
    search (object, required): An object containing the search criteria.
    relevance (object, optional): An object specifying how to calculate relevance scores.
    pageSize (number, optional, default: 10): The number of search results per page.
    page (number, optional, default: 1): The page number to retrieve.
    userId (string, optional): If provided, the search results will be personalized for this user.
    scenarioId (string, optional): The identifier of a specific search scenario you want to use.
    brParams (object, optional): An object containing business rule parameters.
    itemFilters (array, optional): An array of filter objects to narrow down the search results.
    itemBoosters (array, optional): An array of booster objects to influence the ranking of search results.
    Example:

    Top Items with Pagination#

    This method retrieves the top-rated or most popular items with pagination support.
    Parameters:
    filters (object, optional): An object containing filters to apply to the top items.
    pageSize (number, optional, default: 10): The number of top items per page.
    page (number, optional, default: 1): The page number to retrieve.
    scenarioId (string, optional): The identifier of a specific scenario you want to use.
    brParams (object, optional): An object containing business rule parameters.
    itemFilters (array, optional): An array of filter objects to narrow down the top items.
    itemBoosters (array, optional): An array of booster objects to influence the ranking of top items.
    Example:

    Adding Interactions#

    To track user interactions with items, use the addInteraction method:
    The interactionData parameter is an object containing details about the interaction:
    user_id (string, required): The unique identifier of the user who performed the action.
    item_id (string, required): The unique identifier of the item the user interacted with.
    action (string, required): The type of interaction (e.g., 'purchases', 'detailviews', 'ratings', 'cartadditions', 'bookmarks', 'viewportions').
    timestamp (number, optional): The time of the interaction in milliseconds since the Unix epoch. If not provided, the current time will be used.
    cascadeCreate (boolean, optional): If true, the user and item will be created if they don't exist in the database.
    Depending on the action type, additional parameters are required:
    For purchases and cartadditions:
    price (number, required): The price of the item.
    amount (number, required): The quantity of items involved in the interaction.
    For ratings:
    rating (number, required): The rating value, range from -1 to 1.
    For detailviews:
    duration (number, optional): The view duration, defaults to 1.
    For viewportions:
    portion (number, required): The portion of content viewed, range from 0 to 1.
    Example:

    Updating Interactions#

    To update an existing interaction, use the patchInteraction method:
    The interactionData parameter must include all these required fields to identify the specific interaction to update:
    user_id (string, required): The unique identifier of the user.
    item_id (string, required): The unique identifier of the item.
    action (string, required): The type of interaction.
    timestamp (number, required): The exact timestamp of the interaction to update.
    Then include any additional fields you want to update, based on the action type (e.g., price, amount, rating, etc.).
    Example:
    Note: The patchInteraction method requires that the interaction with the exact user_id, item_id, action, and timestamp already exists in the system. If no such interaction is found, you'll receive an "interaction_not_found" error with a 404 status code.

    Understanding Pagination#

    The Recomms AI SDK supports pagination for all recommendation and search methods. Here's what you need to know:

    Pagination Parameters#

    pageSize: The number of results to return per page (maximum 100)
    page: The page number to retrieve (starting from 1)

    Pagination Response#

    All methods that support pagination return a response object with:
    Data array (items): The actual recommendation or search results
    pagination object containing:
    page: The current page number
    pageSize: The number of results per page
    total_results: The total number of results available
    total_pages: The total number of pages available

    Error Handling#

    It's important to include error handling in your code to gracefully manage any issues that might arise during API requests. This could include network errors, authentication problems, or other unexpected issues.

    Best Practices#

    1.
    Secure Your API Key: Never expose your Recomms AI public key in client-side code. Instead, make API calls from your server and pass the results to the client.
    2.
    Rate Limiting: Be mindful of how often you're making requests. Implement rate limiting in your application to avoid overloading the Recomms AI servers.
    3.
    Caching: Consider caching recommendation results for a short period to improve performance and reduce API calls.
    4.
    Pagination: Use appropriate page sizes to balance between user experience and performance. Large page sizes can increase response time.
    5.
    Error Handling: Always include error handling in your code to gracefully manage any issues that might arise.
    6.
    Testing: Thoroughly test your integration with the SDK in a development environment before deploying to production.

    Filters and Boosters#

    Filters and boosters are powerful tools for refining recommendations and search results. Here's a more detailed explanation of how to use them:

    Filters#

    Filters allow you to narrow down the results based on specific criteria. Each filter is an object with the following properties:
    field: The name of the property you want to filter on.
    condition: The type of comparison to make. Common conditions include:
    eq: Equal to
    ne: Not equal to
    gt: Greater than
    gte: Greater than or equal to
    lt: Less than
    lte: Less than or equal to
    value: The value to compare against.
    Example filter:
    This filter would only include items in the 'electronics' category.

    Boosters#

    Boosters allow you to influence the ranking of results. Each booster is an object with the following properties:
    field: The name of the property you want to boost on.
    condition: The type of comparison to make (same as filters).
    value: The value to compare against.
    boost: A number indicating how much to boost matching items. Values greater than 1 increase the importance, while values between 0 and 1 decrease it.
    Example booster:
    This booster would increase the ranking of items with a rating greater than 4.

    Conclusion#

    The Recomms AI SDK provides a powerful set of tools for integrating personalized recommendations, search functionality, and interaction tracking into your JavaScript applications. With the pagination support, you can create even more dynamic and user-friendly experiences.
    Remember to always refer to the most up-to-date documentation provided by Recomms AI, as the SDK may be updated with new features or changes over time. If you encounter any issues or have questions not covered in this guide, don't hesitate to reach out to Recomms AI support for assistance.
    Happy coding with Recomms AI!
    Modified at 2025-03-15 12:29:02
    Previous
    Documentation
    Next
    Create an item
    Built with