Enterprise Edition

Enterprise Destinations

Cloud Edition

Cloud Destinations

Sources & SDKs

In this Section:

MetaRouter Cloud

MetaRouter Cloud Edition is our SaaS offering. This is different from our Enterprise edition in that we run the infrastructure in our cloud rather than deploying to your private cloud or running in a docker container on your local machine.

Cloud is where many of our customers start their journey with streaming data, while Enterprise is typically used by larger companies that have outgrown SaaS and would like to keep all of their data in their own environment. To get started setting up, sign up for MetaRouter Cloud here.

Why Cloud?

The key to delighting customers is understanding them. Since identifying what they do-or don't do-is crucial to understanding their actions, thousands of tools exist to help marketers and product managers analyze user engagement with a website or app. As if selecting the right tools isn't challenging enough, accessing the fast-accumulating data for internal analysis is often a struggle, and the cost of switching to a better tool down the road can result in a major loss of data.

The MetaRouter Cloud Platform allows you to capture every user event from web, mobile, and server side sources. Once those events are ingested into our platform, we can push them to a data warehouse, CRM, or analytics tool of your choice. Implementing our Cloud Platform allows you to better understand how exactly users are interacting with your web and mobile apps so that you can tailor marketing and product focus accordingly.

Getting Started

Once you've signed up for an account, it only takes a few minutes to start collecting valuable behavior data with MetaRouter.

Use one of our library sources to record user data from your website, mobile app, or servers. We'll transform and route that data to all of the destinations you've enabled.

Sources

Collecting customer data from your website, mobile app, or servers is easy, and we've built an integration with each of the following platforms.

Check it out:

Destinations

Check out the list below to explore all of the destinations available with MetaRouter. From there, make your way to each destination's docs and setup guide to see how to use them!

Source/Destination Compatibility Matrix

Client Server Mobile
Acquisio ✔ x x
Adobe Analytics ✔ x x
Amazon Kinesis ✔ ✔ ✔
Amazon Redshift ✔ ✔ ✔
Amplitude ✔ ✔ ✔
Attribution ✔ ✔ x
Bloom Reach ✔ x x
Braze ✔ ✔ x
Calq x ✔ ✔
Clicky ✔ x x
Criteo ✔ x x
Customer.io ✔ ✔ ✔
DoubleClick ✔ x x
Drift ✔ x x
Facebook App Events x ✔ ✔
Facebook Pixel ✔ x x
Google AdWords ✔ x ✔
Google Analytics ✔ ✔ ✔
Google BigQuery ✔ ✔ ✔
Google Tag Manager ✔ x x
Google Firebase x x ✔
Heap Analytics ✔ ✔ ✔
HubSpot ✔ ✔ ✔
Intercom ✔ ✔ ✔
Keen ✔ ✔ ✔
Kenshoo ✔ x x
KISSmetrics ✔ ✔ ✔
Lucky Orange ✔ x x
Lytics ✔ ✔ ✔
Microsoft Ads ✔ x x
Mixpanel ✔ ✔ ✔
Netmining ✔ x x
Optimizely ✔ x x
OutBrain ✔ x x
Pebble Post ✔ x x
Resonate ✔ x x
Retention Science ✔ x x
Rubicon ✔ x x
S3 Event Logs ✔ ✔ ✔
Sailthru ✔ ✔ ✔
Taboola ✔ x x
Twitter Ads ✔ x x
VWO ✔ x x
Webhooks ✔ ✔ ✔
Woopra ✔ ✔ ✔

Calls

Here, we outline the different types of customer data we capture and how to implement them for your business.

In this Section:

Cloud API

Houston - MetaRouter's GraphQL API

Houston is a GraphQL API (utilizing Apollo) that allows interaction with the MetaRouter Data Engineering Platform. Named after NASA’s Johnson Space Center in Houston, it provides direct communication and orchestration over our platform services.

API Explorer

You can explore the API directly using GraphQL Explorer for testing purposes. You will want to make sure you select "MetaRouter Houston" when interfacing with this tool.

Connecting

We recommend using these projects while connecting to GraphQL:

Authentication

JSON Web Tokens

JSON Web Tokens (JWT) encrypt important user session data in a way for our system to validate into a string that you can pass with every request. These tokens are set to expire on our system 24 hours after they are created.

Requesting JWT Access

In order to generate a JWT, you will first need a user account with MetaRouter. Once you have a user account, the follow mutation (updated with your email, as the username, and password) will respond with your Token string for you to pass to our API.

mutation createToken {
  createToken(username: "someone@somewhere.com", password: "password") {
    success
    message
    token
    decoded {
      id
    }
  }
}

Accessing the Public API

Using a JWT

Once you have created a JSON Web Token, you need to embed it in the header of each request as authorization. Additionally, any operation to edit an Organization or any Connection or pipeline that an Organization controls will require that Organization’s ID in the header of your request as well, under organization.

JWT will expire after 24 hours. Once it is expired, you will need to generate a new JWT and replace the expired one with it.

Using an API Key

We’re working to provide trusted partners with API Keys that provide access to the Public API and do not self-expire. Stay tuned for updates, or send us a note at support@metarouter.io if you would like to be notified when this feature is made available.

Data Models

Users and Organizations

In order to access and control pipelines in the MetaRouter platform, we give control of these operations to Organizations. Users are added to Organizations in order to utilize the org's control over those pipelines. Once a person is added to an Organization, they are titled either Owner or User.

Organization Owners have full read/write control over everything linked to that Organization, from editing pipelines to expanding User permissions. You can consider this role as having administrative privileges for this Organization.

Organization Users have specific read/write control over pipelines linked to that Organization, however cannot read the contents of Connections and cannot change access of other Users to their Organization.

Creating and Editing Users

A user account is tied to a specific email address and has to be confirmed via an emailed link. User accounts can be created either via self signup or auto signup. Self Signup assumes that you will configure both your email address and password by yourself, while auto signup assumes you only have the email address for the account you want to configure and the email account holder will need to create their own password.

To create a new user account with the API, use the createNewUser mutation below. Note that the profile argument is optional, however email and password are required.

mutation {
  createNewUser(
    email: "someone.new@somewhere.com"
    password: "password_string"
    profile: {
      {
        firstName: "Someone",
        lastName: "New",
        company: "My Company"
      }
    }
  ) {
    success
    message
    token
    decoded {
      id
    }
  }
}

There is no direct access to auto signup a user from the API. However the auto signup feature will be automatically triggered when adding a user to your Organization that does not have an existing MetaRouter User account.

Note that editing a user's account and editing organization users are features on our roadmap and will be available soon!

Creating and Editing Organizations

In order to create any pipelines, you must first create an Organization to link those pipelines to. The User who creates an Organization is automatically given the Organization Owner title, giving them access to all possible functionality.

Below is the mutation to create a new Organization:

mutation {
  createOrganization(name: "Human-friendly Organization Name", userId: "123456") {
    success
    message
    id
  }
}

Clickstream Pipelines

Clickstream Pipelines focus on extracting or loading events in as close to real-time as possible.

Sources and Applications

We currently support Analytics.js, servers, analytics-android, analytics-ios and analytics-react-native as sources in our Clickstream module. The SDKs we offer for those platforms forward events to our Clickstream API to be ingested and distributed by our system. These sources are grouped under an Organization, to allow you and other contributors that you specify to have access to view and/or edit them.

Upon source creation, a 21 character long Source ID is generated to identify your Application within our system and to ensure your events are routed to the correct destinations.

Below is the mutation to generate a Clickstream Source within our system:

mutation {
  createApplication(name: "Human-friendly Source Name", platform: "analytics.js", orgId: "1234567890") {
    success
    message
    id
  }
}

Destinations and Integrations

To find how to build the form for a Clickstream Pipeline, you want to query against clickstreamPrototypes. Within that response is a connectionPrototype and configPrototype array that list all the fields can use to configure a destination.

  • propertyName : Key for these values within a
  • clickstreamConfig label : Human-friendly name
  • field type : The form field to display. Some of these are standard (input, boolean, number) and others are more abstract (array, boolean, map). (expansion on all types to follow)

As of right now, the connection has to be saved separately before you save the configuration, as the Id for the connection will be referenced within the configuration. This allows you to reuse the connection for multiple configurations that are for the same platform rather than having to make multiple requests to save them both initially.

Here is an example of the two mutations needed to set up a brand new clickstream destination

mutation {
  createConnection(
    integrationCode: "acquisio"
    details: { apiKey: "123" }
    name: "Friendly Connection Name"
    orgId: "1234567890"
    connectionPrototypeId: "123"
  ) {
    success
    message
    id
  }
}
mutation {
  createIntegration(
    appId: "456"
    integrationCode: "acquisio"
    configPayload:  {
          "events" : [
              "fvsbvsdfbsdfb"
          ]
    }
    connectionId: "123"
    name: "Friendly Application Name"
  ) {
    success
    message
    id
  }
}

Query & Mutation Response

Query Response

Queries typically respond as an array of objects, even if the arguments you pass would limit the response to a single object. For instance, the query organizations will return an array with a single object if you search by orgId, but possibly multiple objects if you search by userId.

Mutation Response

Mutations typically respond with a statusMessage object to alert you on if the mutation you triggered was successful or not. This contains:

  • success : True or False response if the request was successful
  • message : Human-friendly message on what happened
  • id : For operations that create new data, the id of the created object will be returned
  • code : Coming soon...

Actions to mutate data within MetaRouter’s platform tend to follow a "create and update" pattern, where we separate out the functions to make a new object with the ability to change or delete it in order to have strict control over the permissions over data control. For example, anyone can run createOrganization and make a new Organization where they are the owner. However, only Organization owners can run updateOrganization that allows for adding/removing users, updating details, or deleting the org.

Error Response

This is on our roadmap and currently being built out- check back soon for updates!

Developer Tools

API Developer Console

Please contact us directly at support@metarouter.io for access to the main developer console for MetaRouter’s public API.

Within the black Header Area, you want to paste the JWT into the token field and the Organization ID (found within the URL of your Organizations dashboard). This will embed that information within the header of all of your requests within the console and will provide access to query and mutation results for your organization. Make sure you select Prod as your GraphQL endpoint (defaults to Staging on page load) to make sure you are accessing data that resides on MetaRouter's Main Platform.

API Reference Materials

In this Section:

Basic Clickstream Example

How does event collection work?

While MetaRouter can provide value for any company with a website or mobile app, we understand that clickstream data may be conceptually difficult to understand. To make it more digestible, we've thrown together a basic example in which you can get some hands-on experience with our track API call.

2048-4

We crafted this example with a game we all know and love, called 2048. For those who aren't familiar with this game, the objective is to combine like numbers until you've made a 2048 tile. When you play 2048, you are telling the app to either move tiles up, down, left, or right. Each of these movements represents a specific event that is logged by this track call:

{
  "method": "track",
  "request": {
    "integrations": {},
    "context": {
      "page": {
        "path": "/2048/",
        "referrer": "",
        "search": "",
        "title": "MetaRouter's 2048",
        "url": "https://astronomerio.github.io/2048/"
      }
    },
    "properties": {
      "anonymousId": "c027b3e0-07a0-4d64-b537-a157a9f6fa15"
    },
    "event": "up",
    "anonymousId": "c027b3e0-07a0-4d64-b537-a157a9f6fa15",
    "timestamp": "2017-10-26T14:50:53.815Z"
  }
}

Once those events are tracked, they can be pushed to a warehouse or analytics tool of your choice. We've chosen to use Keen, an event data platform made for real-time data application. By tracking our 2048 events to Keen through MetaRouter, we avoid the hassle of implementing various Keen API libraries in our site's framework. With MetaRouter, we just need to enable the proper destination in the UI.

2048-5

You can learn more about our Keen destination here

Let's walk through gameplay to show exactly how events are tracked and logged. We have connected this client-side event tracking to Keen, which then records events in the panels on the right hand side of the page.

Let's start start by pressing the up arrow on our keyboard, moving the tiles to the top of the box.

2048-1

As you can see, the up arrow logs a track API call with the event name up. Once we refresh the page, we will see the event registered in our Keen panels.

2048-2

There you have it; we're well on our way to generating insights based on user event data! We're not done yet, though. We are also able to issue a track call when a user starts a new game.

2048-3

After collecting a more substantial amount of event data, we can track a variety of trends, such as:

  • How far into the game users get before starting a new game
  • Which corner of the board is most popular for users to move to
  • The minimum amount of key strokes it took for someone to win the game.
In this Section:

Compare MetaRouter and Segment Side-by-Side

A/A Test MetaRouter and Segment

If you are unable to test MetaRouter against Segment using an A/B testing method, MetaRouter provides a mechanism to A/A test against Segment.

Set Segment Integrations to Cloud Mode

In order to complete a successful test, integrations need to be moved to cloud mode from inside of your Segment account. This will prevent unforeseen collisions from integration specific libraries accessing global variables.

aa-test1

Note: Please be aware if Segment does not allow for cloud mode for a particular integration there is a risk of client-side collision occurring which may result in bad test results.

Update Your MetaRouter Snippet

Next update your metarouter snippet to point to the testing metalytics snippet:

<script type="text/javascript">
  !function(){var metalytics=window.metalytics=window.metalytics||[];if(!metalytics.initialize)if(metalytics.invoked)window.console&&console.error&&console.error("MetaRouter snippet included twice.");else{metalytics.invoked=!0;metalytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","page","once","off","on"];metalytics.factory=function(t){return function(){var e=Array.prototype.slice.call(arguments);e.unshift(t);metalytics.push(e);return metalytics}};for(var t=0;t<metalytics.methods.length;t++){var e=metalytics.methods[t];metalytics[e]=metalytics.factory(e)}metalytics.load=function(t){var e=document.createElement("script");e.type="text/javascript";e.async=!0;e.src=("https:"===document.location.protocol?"https://":"http://")+"cdn.metarouter.io/analytics.js/v1/"+t+"/metalytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)};metalytics.SNIPPET_VERSION="3.1.0";
  metalytics.load("YOUR_SOURCE_ID");
  metalytics.page()
  }}();
</script>

This will now allow for MetaRouter’s snippet to be run concurrently with Segment’s. Each will fire events independently and events can be tested side-by-side for comparison.

analytics.page('hello segment');
metalytics.page(‘hello metarouter’);
In this Section:

Switching from Segment

While Segment has standardized real-time, vendor-neutral customer event collection, no platform is a perfect fit for everyone. At MetaRouter, we've provided an alternative for those searching for greater flexibility, improved security and event-based pricing.

Switching from Segment to MetaRouter is very simple. Follow the four easy steps below to get up and running with our platform!

Getting Started

Step 1

Sign up for MetaRouter and create a source in the MetaRouter UI.

segment-switch-1

Step 2

Remove your Segment snippet and replace it with our Analytics.js snippet:

<script type="text/javascript">
  !function(){var analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("MetaRouter snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","page","once","off","on"];analytics.factory=function(t){return function(){var e=Array.prototype.slice.call(arguments);e.unshift(t);analytics.push(e);return analytics}};for(var t=0;t<analytics.methods.length;t++){var e=analytics.methods[t];analytics[e]=analytics.factory(e)}analytics.load=function(t){var e=document.createElement("script");e.type="text/javascript";e.async=!0;e.src=("https:"===document.location.protocol?"https://":"http://")+"cdn.metarouter.io/analytics.js/v1/"+t+"/"+t+".js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)};analytics.SNIPPET_VERSION="3.1.0";
  analytics.load("YOUR_SOURCE_ID");
  analytics.page()
  }}();
</script>

Step 3

Step 3: Configure your integrations via the MetaRouter dashboard.

segment-switch-3

Step 4

Step 4: Check the live debugger to make sure your data is flowing.

segment-switch-4

Segment | MetaRouter Merge Guidelines

You've made the switch from Segment to MetaRouter Clickstream and now you want all of your data in one place (including the data from your old Segment account). Merging is an easy process - we’ll walk you through it.

Initial Column Audit

To start, we'd recommend that you take a few minutes to review your existing Segment tables with the tables created by MetaRouter's Clickstream platform. Create a spreadsheet with tables from both platforms side by side to easily identify datatype conflicts.

Here's the SQL to view that information:

SELECT * FROM information_schema.columns
WHERE table_schema = 'example_schema_name'
AND table_name = 'example_table_name'

Datatype Conflicts

If you do identify some datatype conflicts, it's likely that your destination column will be able to accommodate the previous datatype (e.g. varchar(256) or varchar(512) or timestamp with timezone). Check out the following example:

clickstream-merge1

Non-Existent Destination Columns

If you have some columns that don't exist in the destination tables, they'll need to either be dropped from the source (Segment) tables or added manually to the destination tables.

You can do the latter manually via the Alter Table Add Command.

Differing Ordinal Positions

If the ordinal position differs between the two tables, a Bulk Insert ((e.g. INSERT INTO {DESTINATION_TABLE} (SELECT * FROM SOURCE_TABLE}) is slightly more complicated.

From here, you'll have 2 options:

A) Bulk Insert

Here, use the specific column order as the destination tables rather thanSELECT (see below)

clickstream-merge2

B) Unload to S3 and then Copy

This has a few more steps, but will likely be less taxing on your db depending on your row count.

  1. Unload each source table to S3
  2. COPY each file from S3 into the corresponding destination table

Here, you can specify the column order of the destination table that the file should load into.

Please don't hesitate to contact us with any questions as you get set up! You can reach us anytime at support@metarouter.io.

© 2020 MetaRouter

Disclaimer: MetaRouter Cloud leverages code from several of Segment's fabulous library of open-source tools, including their source SDKs, destinations, and core Analytics.js library. As some of the core configurations outlined in our docs are largely identical to Segment's, we often re-purpose, and in some cases copy, directly from Segment's docs. In the cases where we have forked Segment's tools, we acknowledge and attribute all credit to Segment for their creation and subsequent documentation.