NAV

RamenJS v2.0 API Documentation

Welcome to the Ramen Developer Documentation.

v2.0 of the RamenJS API introduces one big addition: support for Anonymous users.

We will be phasing out support for RamenJS v1.0 by October 1st, 2016. Please migrate to v2.0 by then.

Getting Started

Installing RamenJS

There are several ways to install RamenJS:

Supported Platforms

RamenJS can be installed into any web application. Users of Ramen include the following platforms:

Single Page Apps (SPAs)

RamenJS plays nicely with frameworks like Ember, Angular, and more.

Installation

JavaScript

Anonymous Visitors

<script>
  !function(){var e=window._ramen=window._ramen||[];if(!e.initialize){if(e.invoked)return void(window.console&&console.error&&console.error("Ramen snippet included twice."));e.invoked=!0,e.methods=["boot","ready","identify","group","track","page","reset","ask"],e.factory=function(r){return function(){var t=Array.prototype.slice.call(arguments);return t.unshift(r),e.push(t),e}};for(var r=0;r<e.methods.length;r++){var t=e.methods[r];e[t]=e.factory(t)}var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src="https://cdn.ramen.is/assets/ramen.js";var o=document.getElementsByTagName("script")[0];o.parentNode.insertBefore(n,o)}}();

  _ramen.boot('YOUR_ORGANIZATION_ID');
  _ramen.identify()
</script>

You can install RamenJS in seconds by just copy/pasting code onto any page where you want to be able to ask questions with Ramen.

New with v2.0 is our support for anonymous visitors. Prior to v2.0, the RamenJS JavaScript snippet would need to be edited by a developer in order to get all the information into our system, but now you can just copy/paste a static snippet to get started.

Logged-in users

To track logged-in users, you’ll need to pass RamenJS some information about that user. You’ll need to pass a unique ID, and optionally include their name and email.

<script>
  !function(){var e=window._ramen=window._ramen||[];if(!e.initialize){if(e.invoked)return void(window.console&&console.error&&console.error("Ramen snippet included twice."));e.invoked=!0,e.methods=["boot","ready","identify","group","track","page","reset","ask"],e.factory=function(r){return function(){var t=Array.prototype.slice.call(arguments);return t.unshift(r),e.push(t),e}};for(var r=0;r<e.methods.length;r++){var t=e.methods[r];e[t]=e.factory(t)}var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src="https://cdn.ramen.is/assets/ramen.js";var o=document.getElementsByTagName("script")[0];o.parentNode.insertBefore(n,o)}}();

  _ramen.boot('YOUR_ORGANIZATION_ID');

  // To identify logged in users, you'll need to have a
  // developer take a look at everything below this line
  _ramen.identify({
    id: "REPLACE_ME-12345", // Replace with a unique user ID. Could be their email
    email: "REPLACE_ME-customer@example.com", // Replace with their email address
    name: "REPLACE_ME-Bugs Bunny" // Replace with their name
  });

  // Check out our options at http://docs.ramen.is/
</script>

Segment.com

Segment.com is a “customer data hub”. If you already are a Segment customer, you can install Ramen in just a few clicks without needing to write any code or deploy any changes to your application.

RamenJS supports the following Segment methods:

Installation methods

Click the ‘Install via Segment’ button on the Getting Started page of your Ramen Organization.

Wait a couple minutes, and then head over to your application and navigate to a page where Segment’s analytics.js is installed. After refreshing the page a few times, refresh your Getting Started page and you should see that RamenJS is sending data to Ramen.

You can read more about the Ramen/Segment integration on by clicking here.

Learn More About Segment.com

To learn more about Segment, click here

Eager.io

Eager.io lets you install JavaScript libraries at the touch of a button. If you are already using Eager, you can install Ramen in just a few clicks without needing to write any code or deploy any changes to your application.

Installation methods

Click the ‘Install via Eager’ button on the Getting Started page of your Ramen Organization.

Wait a couple minutes, and then head over to your application and navigate to a page where Eager is loaded. After refreshing the page a few times, refresh your Getting Started page and you should see that RamenJS is sending data to Ramen.

Learn More About Eager.io

To learn more about Eager, click here

Ruby on Rails Rubygem

Ramen maintains an official Rubygem for Ruby on Rails applications. The Rubygem is used on Ramen.is itself.

View the Rubygem

Wordpress

Thanks to our integration with Eager, installing RamenJS on Wordpress is a breeze.

Installation methods

Click the ‘Install via Eager’ button on the Getting Started page of your Ramen Organization.

When you are prompted, download and install the Wordpress plugin from Eager.

Wait a couple minutes, and then head over to your application and navigate to a page where Eager is loaded. After refreshing the page a few times, refresh your Getting Started page and you should see that RamenJS is sending data to Ramen.

Drupal

Thanks to our integration with Eager, installing RamenJS on Drupal is a breeze.

Installation methods

Click the ‘Install via Eager’ button on the Getting Started page of your Ramen Organization.

When you are prompted, download and install the Drupal plugin from Eager.

Wait a couple minutes, and then head over to your application and navigate to a page where Eager is loaded. After refreshing the page a few times, refresh your Getting Started page and you should see that RamenJS is sending data to Ramen.

Joomla

Thanks to our integration with Eager, installing RamenJS on Joomla is a breeze.

Installation methods

Click the ‘Install via Eager’ button on the Getting Started page of your Ramen Organization.

When you are prompted, download and install the Joomla plugin from Eager.

Wait a couple minutes, and then head over to your application and navigate to a page where Eager is loaded. After refreshing the page a few times, refresh your Getting Started page and you should see that RamenJS is sending data to Ramen.

Angular

While there is no official library for Angular, we do have an Example App

Pay close attention to the comments on the commits to see what is going on: Commits

RamenJS API

_ramen.boot()

_ramen.boot("09889723985786254", {
  custom_bug_image_url: "https://thecatapi.com/api/images/get?format=src"
});

This is the first method called. It takes two arguments:

organization_id uniquely identifies your Ramen account. It can be found on the Getting Started page.

options is where you can pass in configuration options:

Customization Options

Product Center Options

_ramen.ready()

_ramen.ready(function() {
  window.all_your_amazing_logic();
});

Before RamenJS finishes booting, this method takes a function and pushes it onto a queue. It can be called multiple times. Once RamenJS is booted, these callbacks will be called in the order they were pushed onto the queue.

After RamenJS finishes booting, subsequent calls to _ramen.ready() will result in the function being executed immediately.

_ramen.identify()

This method identifies a visitor. It must be called before RamenJS will ask any questions.

There are three ways to call _ramen.identify()

1. Anonymous Visitor

_ramen.identify();

This will identify an anonymous visitor. The visitor will be tagged as such in Ramen, and you will be able to target questions to anonymous visitors.

You can still identify Anonymous visitors even if you have Secure Mode enabled.

2. Logged-in User

_ramen.identify({
  id: "12345", // Required
  email: "customer@yoursite.com", // Optional
  name: "Bugs Bunny" // Optional
});

This will identify a logged-in user. The user will be recorded in Ramen.

3. Logged-in User w/ Secure Mode

_ramen.identify({
  id: "12345",                    // Required
  email: "customer@yoursite.com", // Optional
  name: "Bugs Bunny",             // Optional
  traits: user_traits             // See Custom Traits
}, {
  timestamp: 1234567890,          // Required
  auth_hash: 'CALCULATED_HASH'    // Required
});

This will identify a logged-in user in Secure Mode. The user will be recorded in Ramen.

See Secure Mode for more information.

_ramen.group()

_ramen.group({
  id: "1234567890",             // Required
  name: "Customer, Inc.",       // Required
  url: "https://customer.com"   // Optional
  traits: company_traits        // See Custom Traits
});

This will assign an identify’d user to a “Company” inside of Ramen.

Secure Mode

Even with Secure Mode enabled, you do not need to pass an additional object to _ramen.group() with the auth_hash.

_ramen.track()

_ramen.track('Logged-in pageview');

This will track a named event that can be used to target a question. You can, for example, target questions at Logged-in Users that have been customers for under 1 day with more than 100 Logged-in pageviews.

You cannot pass any other options to _ramen.track().

_ramen.ask()

_ramen.ask("QUESTION_ID");

This will trigger a question to be asked of the currently identify’d user, but ONLY if they have not already been asked that question.

Force ask

_ramen.ask("QUESTION_ID", {force: true});

This will force a question to be asked regardless of whether or not the currently identify’d user has already been asked this question. This can be handy for certain workflow questions (eg. “Why are you canceling your account?”).

_ramen.page()

_ramen.page();

This records a pageview. You cannot pass it any arguments. It will look at the current value of window.location, pass that value to Ramen, and check to see if the user is eligible to be asked a question.

_ramen.reset()

_ramen.reset();

This will clear the current user. Useful to use when a user logs out of your application. Otherwise, they may keep getting asked questions even after they’re logged out.

Custom Traits

_ramen.identify({
  id: "42",
  name: "Bugs Bunny",
  traits: {
    likes_carrots: true,
    ate_carrot_at: 1234567890
  }
});

_ramen.group({
  id: "421",
  name: "ACME, Inc.",
  traits: {
    employs_coyotes: false,
    ran_into_wall_at: 1234567890
  }
});

Both Customers and Companies can have “Traits” assigned to them. Traits are key/value pairs that can be used for Audience creation:

Traits can be used to create Audiences

Names

Trait names are strings that can contain any letter, any number, underscores (_) and dashes (-). Trait names are case-sensitive.

Types

Trait values can be the following types:

Time types

Time types are declared by ending the trait name in _at. For example:

You can pass in times in the following formats:

Type Casting

The first time RamenJS sees a new trait with a non-null value, it will record the type and cast all future traits to that type.

Customization

Icon

_ramen.boot("kadjf89383hr89", {
  bug_image_url: "https://thecatapi.com/api/images/get?format=src"
});

The RamenJS popups were designed to be minimal so that they would Just Look Good™ on any webpage. The style of the popups cannot be modified, but the icon, the little green Ramen ‘R’, can be chanaged.

Product Center

Product Center is a feature that lets you discuss Features with your Customers. Product Center is only available on certain paid plans.

_ramen.boot("ORG_ID", {
  custom_links: [
    {
      title: 'E-mail support',
      href: 'mailto:support@ramen.is',
    },

    {
      title: 'Chat with support',
      callback: 'Interom("showNewMessage")'
      // ^ Not a typo :) If you want to use
      // Intercom w/ Ramen, this is one way
      // to do that.
    }
  ]
});

We provide a way for you to customize links that appear at the bottom of Product Center.

Custom Links have a title property and either an href or a callback property. hrefs must be full URIs (including protocol, ie. https). callbacks can be JavaScript closures or strings that will be eval’d

You are allowed to provide up to 3 Custom Links.

Placement

<nav>
<ul>
  <li><a href="/account">Your Account</a></li>
  <li><a href="/product-center" class="custom-ramen-trigger">Product Center</a></li>
</ul>
</nav>

<style>
._r-badge:after {
  top: -5px;
  right: -5px;
  background-color: red;
  -webkit-border-radius: 100px;
  -moz-border-radius: 100px;
  border-radius: 100px;
  content: " ";
  height: 18px;
  width: 18px;
  position: absolute;
  font-size: 12px;
  line-height: 16px; 
}

._r-related {
  font-weight: bold;
}
</style>

_ramen.boot("ORG_ID", {
  custom_trigger_class: "custom-ramen-trigger"
});

You can set a custom placement, called a ‘trigger’ for the RamenJS widget so that instead of showing the icon in the bottom right or left corner of the screen, a link in your nav can be used to trigger opening Product Center.

Styling the Custom Trigger

We apply different styles to the RamenJS widget:

  1. When there is a Feature related to the current URL, the widget icon will be full color.
  2. When there are no related features, a grayscale image is used instead.
  3. When there are newly deployed features, a circular red badge is placed over the top right corner of the icon.

When using a customer trigger, we do not attempt to modify the style to reflect state changes. Instead, we will add classes to the element. It will be up to you to style the elements.

Secure Mode

<script>
  _ramen.identify({
    email: 'ryan@ramen.is',
    id: 42,
    name: 'Ryan Angilly'
  }, {
    timestamp: 1234567890,
    auth_hash: '09cc0a69233f1bf41e68ed00b9256fde5a4542e9fdba635fe2a9a4edf9ee1ba1'
  });
</script>

Secure Mode ensures that nobody can spoof being one of your customers. It is disabled by default, because it takes a little extra developer time to setup correctly.

To enable secure mode, you need to add another argument to your _ramen.identify() call. This argument is an object with the following attributes:

Timestamp

ts = Time.now.to_i

ts = Math.floor(new Date()) / 1000)

The timestamp attribute must be a time within the last 15 minutes.

Calculating auth_hash

array = []
array << "ryan@ramen.is"
array << 42
array << "Ryan Angilly"
array << 1234567890
array << "oihs9uhasdg8934y8"
str = array.join(":")
digest = (Digest::SHA256.new << str).to_s
digest #=> "09cc0a69233f1bf41e68ed00b9256fde5a4542e9fdba635fe2a9a4edf9ee1ba1"

The hash is calculated as follows:

  1. Create an array with the following elements:

    • email: eg. "ryan@ramen.is"
    • id: eg. 42
    • name: eg. Ryan Angilly
    • timestamp: eg. 1234567890
    • ORGANIZATION_SECRET_KEY: eg. oihs9uhasdg8934y8

  2. Your array now looks like this: ["ryan@ramen.is", 42, "Ryan Angilly", 1234567890, "oihs9uhasdg8934y8"

  3. Join the elements of that array together with a colon (:) into a string

  4. Your string is now: "ryan@ramen.is:42:Ryan Angilly:1234567890:oihs9uhasdg8934y8"

  5. Generate a SHA256 hash from that string

  6. The SHA256 hash for the string in step 4 is: 09cc0a69233f1bf41e68ed00b9256fde5a4542e9fdba635fe2a9a4edf9ee1ba1

Credits

Weston Platter did a ton of work getting this site up. Tweet him a cat pic

A Cat Gif

Here is a cat gif:

Catz

Copyright Ramen, Inc. 2012 - 2016