Welcome to Fomo
The world's first Social Proof Automation API
Fomo began as an ecommerce plugin, syncing with store orders to showcase sales activity to online visitors in real-time.
Today, Fomo is integrated with 5,500+ websites and powers 500,000,000 notifications per month.
Pending use case, implementing Fomo takes as little as 15 minutes. If you need help integrating with your platform, schedule 30 minutes with our developers.
How it Works
The primary API interaction is with our Events endpoint.
All events are created via POST requests from your app's front-end / backend, a 3rd party integration, or Zapier. Assuming a 200 Response, Event parameters are added to a live data feed and viewable within the Fomo dashboard. You can also Retrieve all events with the API.
This feed of Events is displayed to end-users on your website as animated notifications, based on the Application Settings you provide for a given Fomo Application.
Below are a couple Fomo notifications from Matchaeologist and Growth Marketing Conference:
Matchaeologist sends purchase orders -- Growth Marketing Conference sends ticket sales.
As you can see, the ability to sync Fomo with your branding spans as deeply as your CSS chops. :)
Understanding Events vs Event Types
Fomo is built for scale, with modularity and separation of concerns top-of-mind.
For this reason, Fomo delineates Event parameters (ie: first_name, city, product_name) from a notification's message structure, ie:
"{{ first_name}} from {{ city }} just bought {{ product_name }}!"
Thus, whenever you POST an Event object hash to the Events endpoint, you'll need to include an Event Type ID.
This tells Fomo how to arrange the parameters you've sent, for display to end-users browsing your website.
Creating Event Types
While you could create EventTypes with the Fomo API, we recommend using our application UI instead -- just log in and click the Templates tab.
Pro Tip - Developer Happiness
Many of our users maintain separate Fomo app instances for their dev, staging, and production environments.
If you do this, feel free to reference the event_type_tag in your Event POST requests (vs event_type_id) to reduce the number of dynamic environment variables needed in your application. This merely requires giving Templates the same name during setup.
Available SDKs
We're proud to offer official libraries for the following programming languages.
PHP
Node.js
Python
Ruby
Don't see what you need? Let us know.
Token-based Auth
Before making requests, you need an Auth Token.
To get your Token, log into Fomo and hover Apps (top left) > Your App Name. The auth token will be near the bottom.
Note: API access is only available by default to users on a Paid plan -- you will not see an auth token otherwise. If you need to make test calls before upgrading, send us an email and we'll set it up.
Create an event
Send notification parameters to your live Event feed.
Using the time_ago (timestamps) feature
If you're leveraging the "time_ago" attribute to show timestamps in your events, there's no need to POST any 'created_at' values. Fomo simply uses the derived values from the event record itself.
Retrieve all events
Returns an index of all events.
A future version will include pagination and additional meta attributes.
Summary
Fomo integrates seamlessly on any website through an asynchronous, Javascript widget that points to an auto purge-caching CDN.
This enables both our users as well as our developers to make ongoing improvements without customers ever needing to update the snippet on their site.
Drop the Fomo snippet on your website once, and you're done.
To learn more about how the Fomo snippet works, see our Basic and Advanced documentation.
Basic Usage
Every Fomo widget script tag looks something like this:
<script src="https://www.usefomo.com/api/v1/36K9pUyuj8sukckFW66iCg/load.js" async></script>
The identifier following /api/v1 is your application's client_id, which is safe to share publicly.
If you visit the script tag's source URL, you'll notice a basic object with a few properties and convenience methods.
The following object has been truncated to save space, but can you visit this URL to see the latest object notation.
var fomo = {
version: 1.0,
initiate: function () {
this.applyDefaultStyling();
//Pull in recent events, cache for 40 seconds
var cached = Math.ceil((new Date().getTime() / 1000) / this.cache) * this.cache;
var recentOrders = document.createElement('script');
recentOrders.src = this.settings.fomoUrl + '/js-obj/' + this.clientHash + '/' + this.settings.limit + '/' + cached + '.js';
if (this.isFomoEnabled()) {
document.getElementsByTagName('head')[0].appendChild(recentOrders);
}
else{
console.log("Fomo is currently turned off on this domain. To re-enable, log into Fomo and click Apps > Enable (toggle) next to this website.");
}
},
applyDefaultStyling: function () {
var cssElement = document.createElement('style');
cssElement.innerHTML = this.settings.themeCss;
document.getElementsByTagName('head')[0].appendChild(cssElement);
},
closed: false,
cache: 40,
isFomoEnabled: function () {
var enabled = true;
// Should it hide for mobile?
if (this.settings.hideMobile && this.isMobileDevice()) {
enabled = false;
}
// drop <IE9 support
if (this.isIE() && (this.isIE() === 7 || this.isIE() === 8)){
enabled = false;
}
return enabled;
},
// etc, etc.
}
By default, the Fomo widget fires async to your DOM ready functions, and is loaded with relevant Events that match your Application settings.
You may want to debug Fomo in order to tweak CSS styles, check for Events being pre-loaded, etc.
This can be done with the following methods in your browser's developer console:
// get an array of Event objects that match your application settings
fomo.recentEvents
// check if Fomo is enabled on this page
fomo.isFomoEnabled() // returns true/false
// stop the animation sequence, to 'freeze' a given notification's display CSS
fomo.pause()
// manually trigger fomo's setup procedure
fomo.initiate()
// manually trigger fomo's notification animation sequence (ie, if you have a long initial-delay setting and want to test
fomo.runNotifications()
// display a single notification
var events = fomo.recentEvents;
var event = events[0];
fomo.displayNotification(event);
To enable additional features and debugging tools, see Advanced Functionality below.
Advanced Functionality
For granular control over your Fomo notification logic, enable the manual override setting from the Design > Advanced tab, while logged into the dashboard.
Heads Up
Enabling programatic notification triggers will turn off the default page load strategy. Thus, automatic notifications will stop showing on your website, in exchange for full control.
Example use cases:
- Show a Fomo notifications after a user adds something to their shopping cart
- Stop showing notifications when the user signs up
- Show notifications in rapid succession when a user is looking at a certain page, or area of a page
- Etc
There are many things you can do with gesture-based notifications -- here are a few working examples:
// triggers the Fomo notifications to start showing
fomo.trigger('start')
// example implementation
$('#start-button').on('click', function(){
fomo.trigger('start');
});
Fomo uses local storage to track which event notifications have been shown to users. Adding the optional true parameter to restart the event order.
fomo.trigger('start', true)
// example:
// There are 6 notifications. Your user sees notification #1, then notification #2. Calling fomo.trigger('start', true) will start back at notification #1.
// triggers the fomo notifications to stop
fomo.trigger('stop')
// Shown notifications are tracked by local storage. fomo.trigger('start') will restart notifications without repeating those previously shown.
fomo.trigger('restartOrder')
// Similar to fomo.trigger('start', true), but without triggering start. This is useful for "looping" -- showing notifications that have already been shown.
fomo.trigger('resetCount')
// Resets the "max per page" count; useful for overriding the maximum notifications per page preference, defined in your Application's Display settings.
This setting disables the popup notifications but continues to load the messages from the event, allowing for complete styling control.
How To Activate
Step 1) Within Fomo Admin, go to Design > Advanced.
Step 2) Add Fomo div to your page's HTML. (Required)
Fomo Feed needs to find an element with id='fomo_feed' in order to function.
<div id='fomo_feed'></div>
Step 3) Add some simple CSS to give some spice.
<style>
#fomo_feed{
max-width: 400px;
margin: auto;
text-align: center;
}
</style>
Heads Up
Pending your stylesheet setup, you may experience page content being "pushed down" (or up) when your Fomo Feed functionality kicks in. To prevent this, just add a height of "30px" to div#fomo_feed.
Summary
Fomo can send webhooks to give you a summary of your analytics. These are sent every 4 hours.
All you need to do is provide an endpoint and select your options.
Once your webhook is saved, you can test so you don't have to wait the 4 hours interval.
A sample payload (JSON).
{"stats":
{"timeframe_from":1474604187, // Unix timsestamp
"timeframe_to":1474618587, // Unix timsestamp
"click":300, // Integer
"display":10 // Integer
}
}
A great third-party resource for testing HTTP request is https://requestb.in
Note: Fomo is not affiliated with RequestBin.





