1 of 17

Tutorial: Data Ingestion

Your first events

Before you can send your first event, make sure you have completed the following steps:

Set up your datamart.
Set up a channel.
Get familiar with your datamart's schema and adapt it if need. Learn everything about ~~schemas~~ in our user guide

Here, we will assume that the channel you have set up is a site. For mobile applications, you can check our ~~guide~~.

Add the mediarithmics tag

Here we are assuming that you want to track user activity on your website.

The mediarithmics is a javascript snippet that needs to be added to all the pages of your website that you wish to track. The code is non-blocking so it will have no impact on the page rendering time.

Getting the tag

Here is the base snippet for the tag:

<script type="text/javascript">
    /* YOU SHOULD NOT EDIT THIS PART */
    !function(a,b,c){"use strict";function d(a){var b=e[c]||{};e[c]=b,b[a]||(b[a]=function(){e._queue[c].push({method:a,args:Array.prototype.slice.apply(arguments)})})}var e=a.scimhtiraidem||{},f="init call config push pushDefault addProperties addProperty onFinish onStart _reset".split(" ");e._queue=e._queue||{},e._names=e._names||[],e._names.push(c),e._queue[c]=e._queue[c]||[],e._startTime=(new Date).getTime(),e._snippetVersion="2.0";for(var g=0;g<f.length;g++)d(f[g]);a.scimhtiraidem=e,a[c]=e[c];var h=b.createElement("script");h.setAttribute("type","text/javascript"),h.setAttribute("src","https://static.mediarithmics.com/tag/1/tag.min.js"),h.setAttribute("async","true"),b.getElementsByTagName("script")[0].parentNode.appendChild(h)}(window,document,"mics");

    mics.init("<SITE_TOKEN>");
</script>

There are a few things we should unpack here.

The line below the "YOU SHOULD NOT EDIT THIS PART" comment is where we load our tag asynchronously. Obviously, you should not edit this part.

For the tag to work correctly, you should replace <SITE_TOKEN> with your own site token. Your site token can be found in the UI:

connect to the mediarithmics platform
navigate to settings

then Datamart > Channels
you can see your site token in the "Token" column of the channels list

So if your site token is my-site-token, your tag should look like this:

Adding the tag

Now let's add the tag to your site. Let's see 2 ways you can do this:

You can add it directly in the head tag of your site
You can add it using Google Tag Manager, or any other tag management software you're using

In the Head tag

Simply add the tag between the <head></head> part of your page. Like so:

<head>
    <title>My site</title>
    <meta name="description" content="My site is awesome">
    <script type="text/javascript">
        /* YOU SHOULD NOT EDIT THIS PART */
        !function(a,b,c){"use strict";function d(a){var b=e[c]||{};e[c]=b,b[a]||(b[a]=function(){e._queue[c].push({method:a,args:Array.prototype.slice.apply(arguments)})})}var e=a.scimhtiraidem||{},f="init call config push pushDefault addProperties addProperty onFinish onStart _reset".split(" ");e._queue=e._queue||{},e._names=e._names||[],e._names.push(c),e._queue[c]=e._queue[c]||[],e._startTime=(new Date).getTime(),e._snippetVersion="2.0";for(var g=0;g<f.length;g++)d(f[g]);a.scimhtiraidem=e,a[c]=e[c];var h=b.createElement("script");h.setAttribute("type","text/javascript"),h.setAttribute("src","https://static.mediarithmics.com/tag/2/tag.min.js"),h.setAttribute("async","true"),b.getElementsByTagName("script")[0].parentNode.appendChild(h)}(window,document,"mics");

        mics.init("my-site-token");
    </script>
</head>

Using a tag management software

Tag management softwares like Google Tag Manager allow you to manage the tags added to your site within an external platform.

If you're using a tag management software, you can use it to load the mediarithmics tag.

Send events using the tag

Here we are assuming that you've already added the mediarithmics tag to your website and that you are ready to start tracking user activity.

An event is basically something user-relted that you would like to track. For instance, adding something to the cart or reading an article.

An event is composed of:

a name
properties such as a timestamp (when the event took place), ...

Sending events using the mediarithmics is very easy. Just use the push method, below your tag initialization:

And that's it, you've sent your first event. Congratulations!

You can name the event anything you want. Let's say for now you are tracking which product users view. So let's call your event "product-view" in the following examples.

Adding event properties

Let's add some properties to our event, for example the category of the product viewed by the user.

<script type="text/javascript">
    /* YOU SHOULD NOT EDIT THIS PART */
    !function(a,b,c){"use strict";function d(a){var b=e[c]||{};e[c]=b,b[a]||(b[a]=function(){e._queue[c].push({method:a,args:Array.prototype.slice.apply(arguments)})})}var e=a.scimhtiraidem||{},f="init call config push pushDefault addProperties addProperty onFinish onStart _reset".split(" ");e._queue=e._queue||{},e._names=e._names||[],e._names.push(c),e._queue[c]=e._queue[c]||[],e._startTime=(new Date).getTime(),e._snippetVersion="2.0";for(var g=0;g<f.length;g++)d(f[g]);a.scimhtiraidem=e,a[c]=e[c];var h=b.createElement("script");h.setAttribute("type","text/javascript"),h.setAttribute("src","https://static.mediarithmics.com/tag/1/tag.min.js"),h.setAttribute("async","true"),b.getElementsByTagName("script")[0].parentNode.appendChild(h)}(window,document,"mics");

    mics.init("<SITE_TOKEN>");

    mics.push(
        "product-view",
        {
            "category_id": 53,
            "category_name": "Smartphones"
        }
    );
</script>

As you can see, you can add any additional information with your event. However, if you want the events you send to be correctly interpreted by mediarithmics, you have to make sure that the properties you send match you schema configured for the datamart your channel (site) is attached to.

Finding the UserEvent type in your schema

To learn about what a schema is and how to edit it, checkout the ~~schema~~ section in our user guide.

What we need to look at is the UserEvent (or the type that mirrors UserEvent). For instance you could have something like this:

or something like this:

In the first case, we will look at the UserEvent object, in the second case, the ActivityEvent object that mirrors the UserEvent object type.

If you don't have an UserEvent

Matching your schema

Now that we've found the UserEvent type, we have to look at the properties it has.

In our example, there are only 3 properties: id, timestamp and name. id and timestamp will be autogenerated by the system, so the only info we can add is the name. That's what we do when we send a event this way:

But now let's consider that we've added some properties to our schema. For instance, when a user gets to the cart page, I want to track the items which are in his/her cart. Each item will have a brand name and its own name.

Your UserEvent type should look something like this:

Now if you want to send this information along with your event, you have to match the structure of your schema, the name of your event being the 1st parameter in the push method, and the 2nd parameter containing all non system-generated properties (remember: UserEvent

Standard events

As you've seen, you can give your events any name you would like. However you might want to considering mediarithmics standard event names (notice the "$" in front of the event name):

$page_view: the user has seen a page. This is the default event that you can send using the mics.pushDefault() method instead of mics.push(...). Please note that currently $page_view events are discarded after a while.
$home_view: the user has seen the home page

Your first bulk imports

Bulk imports let you directly upload data to mediarithmics, without using the mediarithmics tag.

In contrast with the mediarithmics tag which lets you send only events, bulk imports let you upload different types of data:

UserActivity (offline purchase import, store visit, ...)
UserSegment (email list import, cookie list import, user account list import)

API basics

The mediarithmics is a REST API, supporting the JSON format (you should add the 'Content-Type: application/json' to your requests), both for requests and responses.

The base URL for the API is https://api.mediarithmics.com (make sure to use https as http support has been dropped).

Authentication

There are three ways you can authenticate on the mediarithmics API:

Long-term API tokens
Signature authentication

Check our guide on Authentication for a complete view.

In our example we will generate and use a long-term API token in the UI:

connect to the
navigate to settings
then My Account > API Tokens

We will now use this token in the Authorization header of all our requests to the mediarithmics API.

Your first API call

Now let's take our long-term API token and make our first API call. You will need to add 2 headers to your request to make it work:

Content-Type with the value application/json
Authorization with your API token as value

And there your are!

You'll notice that responses are formatted a bit like this:

Check out our ~~api guide~~ if you want to learn about the different response formats.

Also you can check our ~~API reference~~ for a complete list of endpoints.

Send documents using the API

Now that you know the basics about the mediarithmics, let's see how bulk imports work.

Requirements

Imported data must comply with the following requirements:

the maximum size of the data that can be uploaded is 100 Mo
the data format should match the Content-Type configured on the Document Import (e.g. it must be formatted using CSV or NDJSON

Sending documents

You'll first need to create a document import, then you'll be able to launch executions.

Create a document import

The first step if you want to use bulk imports is to create a document import. See this as creating a configuration for your imports of the same type.

Creating a document import is done with a simple request to POST /v1/datamarts//documents_imports. Let's create a document import for user activities that we will call "My user activity document import". You will need to replace <DATAMART_ID> with your datamart id (which can be found in the UI in Settings > Datamart > Datamarts) and <YOUR_API_TOKEN> with your authentication token.

curl -X POST \
  https://api.mediarithmics.com/v1/datamarts/<DATAMART_ID>/document_imports \
  -H 'Authorization: <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
	"document_type": "USER_ACTIVITY",
	"mime_type": "APPLICATION_X_NDJSON",
	"encoding": "utf-8",
	"name": "My user activity document import"
}'

Let's unpack this:

for document_type we have chosen USER_ACTIVITY in order to send user activities. Other valid values would be USER_SEGMENT, USER_PROFILE, USER_IDENTIFIERS_ASSOCIATION_DECLARATIONS
mime_type should match the type of format you will use for your data. Valid values are APPLICATION_X_NDJSON (if you will send data in a NDJSON format) or TEXT_CSV (if you format your data as comma-separated values). In the case of USER_ACTIVITY, only NDJSON is valid
encoding is the encoding of the data that will be imported
name is the name you want to give this document import

See the ~~API documentation on this endpoint~~ or our guide on ~~document imports~~ for more information on the other types of document.If everything went well, the response should look something like this:

Let's take note of provided the <DOCUMENT_IMPORT_ID>.

Once we have created our document import, we can start creating executions (i.e. actually sending data!).

Let's send some store visits. First, we will prepare our JSON file:

Please check ~~our guide on user activity imports~~ for a complete explanation of all the properties in our payload.

Now we will convert our JSON file to NDJSON and send in the body of the following request. If you want to learn more about the NDJSON format, check out .

You will need to replace <DATAMART_ID> with your datamart id, <DOCUMENT_IMPORT_ID> with the document import id you got in the previous request and <YOUR_API_TOKEN> with your authentication token.

Please note that your Content-Type header must match the mime_type you set when creating the document import earlier.

The response should look like this:

Take note of the <DOCUMENTATION_IMPORT_EXECUTION_ID> here, you will need it if you want to check the status of your execution.

You can check the status of your execution with this simple request:

The response should look like this:

Notice the PENDING status: after a while, the execution will be processed and if you check again, status will be changed to RUNNING then to SUCCEEDED.

Sending documents

You'll first need to create a document import, then you'll be able to launch executions.

Create a document import

The first step if you want to use bulk imports is to create a document import. See this as creating a configuration for your imports of the same type.

curl -X POST \
  https://api.mediarithmics.com/v1/datamarts/<DATAMART_ID>/document_imports \
  -H 'Authorization: <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
	"document_type": "USER_ACTIVITY",
	"mime_type": "APPLICATION_X_NDJSON",
	"encoding": "utf-8",
	"name": "My user activity document import"
}'

Let's unpack this:

for document_type we have chosen USER_ACTIVITY in order to send user activities. Other valid values would be USER_SEGMENT, USER_PROFILE, USER_IDENTIFIERS_ASSOCIATION_DECLARATIONS
mime_type should match the type of format you will use for your data. Valid values are APPLICATION_X_NDJSON (if you will send data in a NDJSON format) or TEXT_CSV (if you format your data as comma-separated values). In the case of USER_ACTIVITY, only NDJSON is valid
encoding is the encoding of the data that will be imported
name is the name you want to give this document import

Let's take note of provided the <DOCUMENT_IMPORT_ID>.

Once we have created our document import, we can start creating executions (i.e. actually sending data!).

Let's send some store visits. First, we will prepare our JSON file:

Please check ~~our guide on user activity imports~~ for a complete explanation of all the properties in our payload.

Now we will convert our JSON file to NDJSON and send in the body of the following request. If you want to learn more about the NDJSON format, check out .

Please note that your Content-Type header must match the mime_type you set when creating the document import earlier.

The response should look like this:

Take note of the <DOCUMENTATION_IMPORT_EXECUTION_ID> here, you will need it if you want to check the status of your execution.

You can check the status of your execution with this simple request:

The response should look like this:

Notice the PENDING status: after a while, the execution will be processed and if you check again, status will be changed to RUNNING then to SUCCEEDED.

Tutorial: Data Ingestion

Your first events

Add the mediarithmics tag

Getting the tag

Adding the tag

In the Head tag

Using a tag management software

Send events using the tag

Adding event properties

Finding the UserEvent type in your schema

Matching your schema

Standard events

Your first bulk imports

API basics

Authentication

Your first API call

Send documents using the API

Requirements

Sending documents

Create a document import

Add the mediarithmics tag

Your first events

Getting the tag

Tutorial: Data Ingestion

Adding the tag

In the Head tag

Using a tag management software

API basics

Send events using the tag

Matching your schema

Finding the UserEvent type in your schema

Standard events

Requirements

Your first bulk imports

Adding event properties

Authentication

Send documents using the API

Your first API call

Sending documents

Create a document import

Create a document import execution

Checking your document import execution status