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:
- Ruby on Rails
- Django
- Angular
- Meteor.js
- Wordpress
- Joomla
- Drupal
- PHP
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:
identify
group
track
page
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.
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
: String, requiredoptions
: Object, optional
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
custom_bug_image_url
: See Customization
Product Center Options
custom_trigger_id
: See Product Centercustom_trigger_class
: See Product Centercustom_links
: See Product Center
_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:
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:
- String
- Boolean
- Integer
- Float
- Time (See below)
Time types
Time types are declared by ending the trait
name in _at
. For example:
last_seen_at
upgraded_at
You can pass in times in the following formats:
- Epoch seconds:
1234567890
- XML Schema:
2009-02-13T23:31:30Z
(UTC) or2009-02-13T16:31:30-07:00
(with offset)
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.
Custom Links
_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. href
s
must be full URIs (including protocol, ie. https).
callback
s 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:
- When there is a Feature related to the current URL, the widget icon will be full color.
- When there are no related features, a grayscale image is used instead.
- 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.
_r-related
: We will add this class when there are Features related to the current URL_r-badge
: We will add this class when there are newly deployed features that have not yet been seen by your customers.
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
: The current time in epoch secondsauth_hash
: A SHA-256 hash
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:
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
Your array now looks like this:
["ryan@ramen.is", 42, "Ryan Angilly", 1234567890, "oihs9uhasdg8934y8"
Join the elements of that array together with a colon (
:
) into a stringYour string is now:
"ryan@ramen.is:42:Ryan Angilly:1234567890:oihs9uhasdg8934y8"
Generate a SHA256 hash from that string
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:
Copyright Ramen, Inc. 2012 - 2016