DOCSEARCHbyAlgolia
Submit Docs

Searchjoy Documentation

repository·master·Indexed 20 days ago

https://github.com/ankane/searchjoy

A search analytics tool for Rails that provides real-time visibility into search queries, conversion rates, and top search performance. It works with any search platform (such as Elasticsearch or Solr) and offers deep integration with Searchkick for automated tracking. Key features include a dashboard for monitoring, manual and automatic search tracking, conversion tracking, and data retention management.

Tokens
2.5K
Snippets
10
Records
11
Agent score
70%

What's inside Searchjoy

  1. Install Searchjoy

    master

    To install Searchjoy in your Rails application, add the gem to your Gemfile, run the installation generator to create the necessary database migrations, and mount the engine in your routes.

    Note: You must protect the dashboard endpoint in production using authentication (see the Authentication section).

    # 1. Add to Gemfile
gem "searchjoy"
    # 2. Run generator and migrate
rails generate searchjoy:install
rails db:migrate
    # 3. Mount in config/routes.rb
mount Searchjoy::Engine, at: "searchjoy"

  2. Manage Searchjoy data retention

    master

    To comply with data retention policies, you can delete old search and conversion data.

    Bulk Deletion

    When deleting searches, ensure you also delete associated Searchjoy::Conversion records to maintain data integrity.

    Aggregation

    You can use Rollup to aggregate important data before deletion using Searchjoy::Search.rollup("Name").

    # Delete searches and conversions older than 1 year
Searchjoy::Search.where("created_at < ?", 1.year.ago).find_in_batches do |searches|
  search_ids = searches.map(&:id)
  Searchjoy::Conversion.where(search_id: search_ids).delete_all
  Searchjoy::Search.where(id: search_ids).delete_all
end

# Delete data for a specific user
user_id = 123
search_ids = Searchjoy::Search.where(user_id: user_id).pluck(:id)
Searchjoy::Conversion.where(search_id: search_ids).delete_all
Searchjoy::Search.where(id: search_ids).delete_all

  3. Track conversions

    master

    Conversions track when a user performs a desired action (like adding an item to a cart) following a search.

    1. Capture the Search ID: When a user searches, retrieve the search ID from the results.
    2. Call convert: When the conversion event occurs, find the corresponding Searchjoy::Search record and call .convert on it. You can optionally pass the model instance that was converted to provide more detail.
    # 1. Get the search ID (using Searchkick)
results = Item.search("apple", track: true)
sid = results.search.id

# 2. Convert the search
search = Searchjoy::Search.find(params[:id])
search.convert # Basic conversion
# OR
search.convert(item) # Conversion with specific model

  4. Track searches manually or with Searchkick

    master

    You can track searches by creating a Searchjoy::Search record. This allows you to monitor real-time queries and performance.

    Manual Tracking

    Use Searchjoy::Search.create to record a search. You can add custom attributes by adding columns to the searchjoy_searches table.

    Automatic Tracking with Searchkick

    If you use Searchkick, you can use the track option to automate this process. You can pass additional attributes via the track hash.

    # Manual tracking
Searchjoy::Search.create(
  search_type: "Item", # typically the model name
  query: "apple",
  results_count: 12,
  user_id: 1
)

# Automatic tracking with Searchkick
Item.search("apple", track: {user_id: 1})

# Tracking custom attributes (requires adding column to searchjoy_searches table first)
Item.search("apple", track: {user_id: 1, source: "web"})

  5. Protect the Searchjoy dashboard with authentication

    master

    Since the Searchjoy dashboard is mounted at a public route, you must secure it in production.

    Using Devise

    Wrap the engine mount in a Devise authentication block in config/routes.rb to restrict access to admins.

    Using Basic Authentication

    Set SEARCHJOY_USERNAME and SEARCHJOY_PASSWORD environment variables or in an initializer to enable Basic Auth.

    # Devise approach in config/routes.rb
authenticate :user, ->(user) { user.admin? } do
  mount Searchjoy::Engine, at: "searchjoy"
end
    # Basic Auth approach via ENV
ENV["SEARCHJOY_USERNAME"] = "andrew"
ENV["SEARCHJOY_PASSWORD"] = "secret"

  6. Configure Searchjoy via initializer

    master

    You can customize the behavior and appearance of the Searchjoy dashboard by creating config/initializers/searchjoy.rb.

    Available configuration options include:

    • Searchjoy.time_zone: Sets the dashboard time zone (defaults to Time.zone).
    • Searchjoy.top_searches: Sets the number of top searches displayed (defaults to 100).
    • Searchjoy.query_url: A lambda that returns a URL to the search results for a given search.
    • Searchjoy.query_name: A lambda to customize the query name shown in the live stream.
    • Searchjoy.conversion_name: A lambda to customize the conversion name shown in the live stream.
    # config/initializers/searchjoy.rb

Searchjoy.time_zone = "Pacific Time (US & Canada)"
Searchjoy.top_searches = 500

# Link to search results
Searchjoy.query_url = ->(search) { Rails.application.routes.url_helpers.items_path(q: search.query) }

# Customize live stream query display
Searchjoy.query_name = ->(search) { "#{search.query} #{search.city}" }

# Customize live stream conversion display
Searchjoy.conversion_name = ->(model) { model.name }

  8. Configure Searchjoy global settings

    master

    Searchjoy provides several configuration attributes to customize how searches and conversions are tracked. These can be set globally on the Searchjoy module.

    Available Configuration Options

    AttributeTypeDefaultDescription
    time_zoneString or ActiveSupport::TimeZonenilSets the time zone used for tracking searches and conversions.
    top_searchesInteger100The number of top searches to retrieve.
    conversion_nameSymbolnilThe name used for conversion tracking.
    query_nameSymbolnilThe name used for query tracking.
    query_urlSymbolnilThe URL used for query tracking.
    multiple_conversionsBooleantrueWhether to allow multiple conversions for a single search.

  9. Integrate Searchjoy with Searchkick

    master
    If you are using Searchkick, you can automatically enable search tracking by calling Searchjoy.attach_to_searchkick!. This method prepends tracking logic to Searchkick::Query and Searchkick::MultiSearch, and adds a :search attribute accessor to Searchkick::Results to allow access to the original search object from the results.
    Searchjoy.attach_to_searchkick!

  10. Backfill conversions in Searchjoy

    master
    If you have existing data in your searches table where converted_at is present, but you haven't yet populated the searchjoy_conversions table, you can use Searchjoy.backfill_conversions to migrate that data. This method finds searches that have a conversion timestamp but no corresponding record in the conversions table and performs a bulk insert.
    Searchjoy.backfill_conversions

  11. Track searches using the track option

    master

    To enable search analytics tracking, pass the track option to your search execution.

    If you pass track: true, Searchjoy will automatically determine the search_type based on the model class name, the provided :models array, or the :index_name.

    If you pass a hash to track, those key-value pairs will be merged into the search record as additional attributes. Tracking only occurs if the search returns results (results.search is truthy).

    # Basic tracking (uses class name as search_type)
searchjoy.search("query", track: true)

# Tracking with custom attributes
searchjoy.search("query", track: { category: "electronics" })

# Tracking with specific models
searchjoy.search("query", track: true, models: [Product, Category])