Getting started

Thank you very much for choosing Vespucci ! Vespucci offers a new productroach to data analysis in which statistical models test hypotheses for you that you may not have thought of.

Vespucci Advanced Techs

Introduction

Vespucci is a native application for Mac. Going native allows us to do things like relying on your Mac's GPU and on the Metal API to perform probabilistic calculations or to exploit the powerful neural network of the Apple Silicon Macs to power our machine learning systems (but don't worry, Vespucci works perfectly on your Intel Macs). It is this native application that will processes the data from your products (mobile apps, websites, backend systems...). We refer to your product(s) as "integrations". This documentation is divided into two main sections. The first one guides you to configure an integration to connect your product with Vespucci. The second section provides a quick introduction to Vespucci, the software that runs on your Mac.


Integration

When we designed Vespucci, we had two constraints in mind: the first was ease of integration. We know that integrating our solution into your products can be seen a very significant non-monetary cost. We worked hard to minimise this cost as much as we could. The second constraint is the transparency of the integration. You entrust us with usage data that is considered increasingly sensitive. You no longer want to deal with black boxes. You want to know what usage data is being retrieved and where it is being sent. Thus we have designed a modular and transparent integration system. You are in the driver seat and you have a hand on key choices at each step of the integration. At the same time, we have designed the process and build virtual assistants to make this process as smooth as possible. Let’s get started !


We have broken down the integration of Vespucci into your Product into four key steps. It sounds long and tedious but in reality it is quite fast and the configuration wizards built into the dashboard automate many of the steps described in this document.

Vespucci Advanced Techs

Let's first make a short summary of these steps before describing them in more detail. It always helps to know where you set foot, doesn't it ? Let's start with the blocks Project and DataPipe. The project is a direct analogy of your product. The DataPipe is the "pipe" through which you will send your project data (i.e. from your product) to the Vespucci servers. We associate to Projects and DataPipes a characteristic element:

  • Each project has a Context. This Context consists in specifying the context data (ip address, device manufacturer) that you want to collect when integrating Vespucci into your product. Don't panic, this step is fully automated and after configuration, Vespucci will automatically generate a file in the programming language of your choice that you will just have to drag and drop into your favourite IDE.

  • A DataPipe is used to transit a DataLayer. This DataLayer serves as a vehicle for the data you want to track.


Step 0: Choose your DataPipe.

The first step is to choose a DataPipe. Indeed, the choice of this one will influence the creation of your project. As we have seen, the DataPipes allows you to send your product data to our servers.

We are offering three families of DataPipes:

  • An API that allows a totally transparent integration while remaining simple and easy to integrate into your product.
  • Segment that allows you to capitalize on your existing data and offers a three-click deployment.
  • An SDKs (Coming Soon), mainly designed for e-commerce solutions, which allows a fully automated installation and deployment.

Let’s see how they compare:

API Segment SDK
Custom Project
Context Configuration
βœ… ❌ ❌
Automatic Data Tracking ❌ ❌ βœ…
No changes to the
App Code
❌ βœ… ❌
Supported Projects iOS, Android, React Native iOS, Android, React Native e-Commerce

Step 1: Create a Project.

A Project must be assimilated to a mobile app or a website on a given platform. Currently, Vespucci allows the creation of projects on the following platforms:

Platform Languages Supported Minimum OS Version DataPipes Supported
iOS Swift, Objective-C iOS 12 API, Segment
Android Java, Kotlin Lollipop 5.1, API level 22 API, Segment
React Native JavaScript N/A API, Segment
Web & Backend JavaScript N/A Segment

The creation of a project is quite simple.

1. First of all, you must go to your Vespucci Dashboard. You can open the Dashboard simply by clicking on the button below. If you don't have a Vespucci user account yet, simply click on "Signup now" at the bottom of the login window. After creating your user account, a wizard will guide you through the creation of your first project.



If you already have a Vespucci user account, you can log in and create a new project using the "Your Active Projects" section as shown in the screenshot below.

Vespucci Advanced Techs

2. You are then asked to specify a name for your project and the DataPipe you want to use. For the API, select one of the available platforms. For the Segment pipe simply specify "Segment Destination" regardless of the platform.


3. Finally, you need to configure the "Tracking Method". If you are creating a project using the DataPipe API, we strongly recommend that you select the "Action Based Tracking" option. If you are using Segment, we invite you to consult this section of our documentation to help you make your choice


Step 2: Configure the Project Context.

The Project Context is a set of metadata allowing to contextualise your user's experience such as her geographical position, the configuration of her device... These metadata are automatically retrieved by Vespucci without any additional configuration from your side. As we promised you, you stay in control. You choose what context information you share. Let us show you how it works:

1. To configure the context of your project, go to your Vespucci Dashboard and click on "Connect" in the upper frame called "DataPush API".



Vespucci Advanced Techs

2. This will reveal a window inviting you to configure the context of one of your projects. Start by selecting the project for which you want to configure the context using the ad-hoc menu.

3. Enter the Bundle-Id of your app.

4. You can now select the data that Vespucci will collect from your customers' devices. Please note that the configuration you make is by no means irreversible. After configuration, the dashboard produces a helper file in the programming language you specify. You must add this file to your preferred IDE. With the exception of react-native projects which require the import of two external libraries, Android or iOS projects do not require any other dependencies than the file produced by the dashboard.


Step 3: Create DataLayers.

The acquisition of data from your products (your projects) is done by means of a "vehicle" that we have called DataLayer. Conceptually, a DataLayer corresponds to a user behavior that you would like to investigate. Depending on the observed behavior, different types of DataLayers can be mobilized.


Vespucci Advanced Techs


  • The layers of the Screen class allow to observe the user's path within the customer's product. They also allow you to measure the commitment associated with a particular screen.

  • The layers of the Action class allow to observe specific and punctual actions triggered by your users (e.g adding a recipe to the favorites, adding an item to the shopping cart...).

In addition, you can attach "DNA" to your Layers. This DNA corresponds to content elements displayed on the screen for which you would like to test the impact in terms of user experience. This "DNA" is at the heart of the Vespucci experience. Our statistical models will use them as variables to determine if they are the cause of a behaviour you specify. Don't be stingy with DNA, add as much as you can even if they seem incongruous at first glance. This is a different productroach to that recommended by many other analytical tools but our tool is different in its design.

DataLayers consist of a line of code that you must add to each view of your product. You can also add additional DataLayers to track a specific action (e.g. add an item to your favourites...). Then we invite you to graft to each of these layers what we call "UXDNA" pieces. These represent elements of the experience, of the content of the product on which you would like to be able to investigate.

Conceptually, DataLayers are very similar to what other platforms offer in terms of tracking. See below an example between Vespucci and Google Firebase.

Tracking the addition of an image from the gallery in Firebase
Analytics.logEvent("share_image", parameters: ["name": name as NSObject,"full_text": text as NSObject])
              
Tracking the addition of an image from the gallery in Vespucci
vespucciTools.sendTrackEvent(eventName: "share_image.", eventProperties: ["name":self.name,"full_text":self.text ])
              

If you use Segment or one of our SDKs you do not have to create DataLayers. These correspond to the tracks and views/pages that you have defined in Segment or are generated automatically (in the case of the SDK).
If you use our API, you have to create the DataLayers manually and copy and paste a snippet of code on each of your views.

Vespucci Advanced Techs

The Dashboard is the best place to perform this task. However, if you would like to get an overview of the implementation you need to do without having to connect to the Dashboard you can consult the sections "API" of this doc.


Segment (Coming Soon)

Getting started

Using Vespucci hand in hand with Segment makes its integration incredibly fast. It takes only a few clicks to start using Vespucci with your data. You don't have to add anything to your product code so you don't have to involve your dev team. An intuitive interface allows you to process the data from Segment by yourself, from Vespucci.

Vespucci Advanced Techs

1. First of all, you must go to your Vespucci Dashboard to create a project.



2. On your Dashboard, within the "Your Active Projects" section click on the "+" button. Enter a name and select "Segment Destination" as the DataPipe.

Vespucci Advanced Techs

3. Then you have to specify the "Tracking Method". This option is a bit less obvious and deserves some explanation. First, let's look at the big picture. You can think of the data from Segment as a stream. This "stream" consists of tracks and views. Vespucci will then consolidate these tracks and views into a session, a concept that does not exist in Segment. A session is a stock. It contains all the tracks and views that are performed by an end user in a single action sequence. You can choose to define this action sequence in two different ways.

  • We call the first approach Action Based Tracking, it consists in defining the session as all the views and all the tracks realized between two remarkable tracks: namely "Application Opened" and "Application Backgrounded". These events are included by default in the Native Mobile Spec of Segment. It is also the most accurate way to consolidate a session.

  • However, it is possible that, for various reasons, your Segment integration does not include the "Application Opened" and "Application Backgrounded" tracks. This is why we introduce a second tracking method called Time Based Tracking. It consists in defining the session on the basis of a temporal criterion. Vespucci will analyze the timestamp of each of the tracks and views sent by segment and try to consolidate them into concurrent events. This approach is less precise than the Action Based Tracking.

Depending on your Segment configuration, select one of the two tracking methods and click Create to create your project.

4. Congratulations! You have created your project. Take note of the API key associated with this project (it appears in the "Your Active Projects" section), you will need it soon. Now you need to connect it with your Segment data. To do this, go to your Segment Dashboard

5. On your Segment Dashboard, from the Destinations Catalog page in the Segment product, click Add Destination.

6. Search for Vespucci in the Destinations Catalog, and select the Vespucci destination.

7. Choose which Source should send data to the Vespucci destination. Enter the API Key in the Vespucci destination settings in Segment. This is the API key you noted in step 4.

DataLayers Reference

A. Segment Page (or Segment Screen).
If you aren't familiar with the Segment Spec, take a look at the Page method documentation or at the Screen method documentation to learn about what it does. An example call would look like:

analytics.page()
or, for a Screen (on Mobile)
[[SEGAnalytics sharedAnalytics] screen:@"Home" properties:@{ @"Feed Type": @"private" }];
Segment sends Page and Screens calls to Vespucci as a screen.

B. Segment Identify.
If you aren't familiar with the Segment Spec, take a look at the Identify method documentation to learn about what it does. An example call would look like:

analytics.identify('userId123', {email: 'john.doe@example.com'});
Segment sends Identify calls to Vespucci as an identify event.

C. Segment Track.
If you aren't familiar with the Segment Spec, take a look at the Track method documentation to learn about what it does. An example call would look like:

analytics.track('Login Button Clicked')
Segment sends Page calls to Vespucci as an action.

DataLayers API

Getting started

Some Layers have to be configured in your project to allow Vespucci to work properly.

Layer Kind Mandatory
Application Opened Action βœ…
Application Closed Action βœ…
View Controller Screen βœ…

iOS API

1. Initial Configuration.

1.1 Track the App opening and closing
If you don't have an Application Scene Manifest in you Info.plist

Go to your AppDelegate.swift file and copy paste the following code in the application didFinishLaunchingWithOptions and applicationWillResignActive methods.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { 
// Override point for customization after application launch.
          
//Vespucci Action Open Event.
vespucciTools.sendTrackEvent(eventName: "Application Opened", eventProperties: [:])
          
return true
}

func applicationWillResignActive(_ application: UIApplication) {
//Vespucci Track Close Event.
vespucciTools.sendTrackEvent(eventName: "Application Backgrounded", eventProperties: [:])
}
If you do have an Application Scene Manifest in you Info.plist

Go to your AppDelegate.swift file and copy paste the following code in the application didFinishLaunchingWithOptions method.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { 
// Override point for customization after application launch.
                      
//Vespucci Action Open Event.
vespucciTools.sendTrackEvent(eventName: "Application Opened", eventProperties: [:])
                      
return true
}

Go to the SceneDelegate.swift file of your App and add the following code:

func sceneDidEnterBackground(_ scene: UIScene) {
  // Called as the scene transitions from the foreground to the background.
  // Use this method to save data, release shared resources, and store enough scene-specific state information
  // to restore the scene back to its current state.
  vespucciTools.sendTrackEvent(eventName: "Application Backgrounded", eventProperties: [:])
}
1.2 Track each of your ViewController

Please copy this code on all your views. Not the majority or almost all of them. All of them. It's going to be tedious but you won't regret the result 😊.

override func viewDidLoad() {
super.viewDidLoad()

// Do any additional setup after loading the view.
let priceValue = 30
vespucciTools.sendViewEvent(viewName:"ProductView", viewProperties:["price":priceValue])
}

2. Track additional Actions.

You can track user-triggered events, such as adding an item to favorites, just like that:

vespucciTools.sendTrackEvent(eventName: "Likes.", eventProperties: ["likes":self.likesCount ])

Android API

1. Initial Configuration.

1.1 Track the App opening

Please add the following code in your application file.

public class AppDemo extends Application {
              // Called when the application is starting, before any other application objects have been created.
              // Overriding this method is totally optional!
              @Override
              public void onCreate() {
                  super.onCreate();
                  // Required initialization logic here!
            
                  vespucciTools.sendTrackEvent("Application Opened", null);
                  registerActivityLifecycleCallbacks(new vespucciTools());
            
              }
            
              // This is called when the overall system is running low on memory,
              // and would like actively running processes to tighten their belts.
              // Overriding this method is totally optional!
              @Override
              public void onLowMemory() {
                  super.onLowMemory();
              }
            }
1.2 Track each of your Activities

Please copy this code on all your activities. Not the majority or almost all of them. All of them. It's going to be tedious but you won't regret the result 😊.

@Override
              protected void onCreate(Bundle savedInstanceState) {
                  super.onCreate(savedInstanceState);
              
                  int priceValue = 30;
                  String categoryValue = "Italian";
              
                  //Code related to the integration of Vespucci.
                  //Creation of the object containing the interface elements to be analyzed.
                  JSONObject vespucciData = new JSONObject();
                  try {
                      vespucciData.put("price", priceValue);
                      vespucciData.put("category", categoryValue);
              
                  } catch (JSONException e) {
                      e.printStackTrace();
                  }
              
                  //Sending information to Vespucci.
                  vespucciTools.sendViewEvent("Product View", vespucciData);
              
                  setContentView(R.layout.activity_main);
                  Toolbar toolbar = findViewById(R.id.toolbar);
                  setSupportActionBar(toolbar);
              }

2. Track additional Actions.

You can track user-triggered events, such as adding an item to favorites, just like that:

JSONObject vespucciData = new JSONObject();
              try {
                vespucciData.put("Likes", likeCount);
            
              } catch (JSONException e) {
                e.printStackTrace();
              }
            
            vespucciTools.sendTrackEvent("Likes", vespucciData);

ReactNative API

1. Initial Configuration.

1.1 Track the App opening and closing

Please add the following code to your index.js file.

AppState.addEventListener('change', state => {
  if (state === 'active') {
    sendTrackEvent("Application Opened", {});
  } else if (state === 'background') {
    sendTrackEvent("Application Backgrounded", {});
  }
});
1.2 Track each of your Screens

Please copy this code on all your screens. Not the majority or almost all of them. All of them. It's going to be tedious but you won't regret the result 😊.

sendViewEvent("product", {price : 100, category: "food"});

2. Track additional Actions.

You can track user-triggered events, such as adding an item to favorites, just like that:

onPress={() => sendTrackEvent("menuClicked", {menu_id: 12, text: "products"})}

Vespucci for Mac

When we designed Vespucci, we had two constraints in mind: the first was ease of integration. We know that integrating our solution into your products can be seen a very significant non-monetary cost. We worked hard to minimise this cost as much as we could. The second constraint is the transparency of the integration. You entrust us with usage data that is considered increasingly sensitive. You no longer want to deal with black boxes. You want to know what usage data is being retrieved and where it is being sent. Thus we have designed a modular and transparent integration system. You are in the driver seat and you have a hand on key choices at each step of the integration. At the same time, we have designed the process and build virtual assistants to make this process as smooth as possible. Let’s get started !


Installation

Vespucci runs on any Mac running macOS 11 (Big Sur) or later. Vespucci is optimised for Apple Silicon Macs and supports the latest Apple technologies. To install Vespucci on your Mac, go to your dashboard.



Once logged in, click on "Download" in the lower left frame titled "Download Vespucci on your Mac". This action will reveal a window in which you will be prompted to request access to Vespucci. Simply click on "Request Access" and we will get back to you shortly. You will then be able to download Vespucci freely from your dashboard using the same window.

Vespucci Advanced Techs

DataSync

In order to perform statistical analysis on large datasets, Vespucci replicates some information from our servers on your Mac. This information comes from your product data usage. It is constantly evolving. Therefore, you need to regularly synchronize Vespucci with our servers to keep the data on which Vespucci builds its models and analyses up to date.


Initial configuration

When using Vespucci on a new Mac, or if you use Vespucci after logging out, the Sync Wizard helps you specify which usage data to bring back to your Mac. Several cases are possible:

No usage data on your Mac.

If Vespucci does not find usage data on your Mac's hard drive, it will prompt you to build a new local database. You can choose to build this database as a replica of the usage data contained on our servers from a given date. You can also choose not to retrieve any data from our servers and create a "blank" database that will be fulfill with usage data from after the configuration.

Vespucci Advanced Techs

Data already exists on your Mac.

If Vespucci finds usage data on your Mac's hard drive, it will ask you to keep it as a basis for future analysis.

You can choose to keep the pre-existing data. In this case, the data configuration wizard will prompt you to repatriate on your Mac the usage data produced after the pre-existing data. You will have the option of importing all of those data or only the data produced within a time range that you can set.

Vespucci Advanced Techs

You can also choose not to keep this data and set up a blank database. The latter case was explained in section "no usage data".

Vespucci Advanced Techs

Keep your data up-to-date.

When using Vespucci, it is important to keep your data up to date. To retrieve all usage data generated since your last synchronization, simply click on the central item in the toolbar called "Tap to Sync Vespucci". This item also shows the date and time of your last synchronisation operation, the date and time from which the new data will be retrieved..

Vespucci Advanced Techs

Stories

Stories are at the heart of the Vespucci experience. They allow you to describe a user behaviour that you will then visualize through dimensions (such as time, geographical location of your users, ...).


What's a Data Story ?

If you develop a meal delivery app you could write the following story: users who placed an order after observing a positive customer review. You will then probably be interested in visualising the geographical areas in which such behaviour is most frequent. This is the role of dimensions. To learn more about dimensions, see the dedicated section.

Create a Story.

To start writing your story, simply click on "Create a Story". In the Lab subscription plan, you can create up to 10 different stories. It can be very handy to have different stories available. For example, you can assign a user behaviour of interest to a story so that you can present it later, for example at a meeting.

Vespucci Advanced Techs

The Story Editor.

The opening of a story initiates the story editor. The upper part of the story editor allows you to define your story as the active story, i.e. the one you will view through the dimensions. The lower part of the story editor allows you to configure your story itself.

Vespucci Advanced Techs

A story is built around four functional blocks:

(i) User behaviour

The first two (the cyan blue) blocks invite you to specify the behaviour you would like to observe. This is a kind of description of what you would observe on a video recording.
You may be interested in a specific user experience. In this case, select the option "A Given Journey" in the first block. In the second block, Vespucci will then present you with a list of all the Views or Screens from Segment and invite you to describe the transition from one view to another.
You may also be interested in a specific action. In this case, select the option "A Given Action" in the first block. In the second block, Vespucci will then present you with a list of all "Track" objects from Segment and invite you to select one of them.

(ii) Behaviour Determinant

The last two blocks are concerned with the determinant (the "driver") of the user behaviour that you have specified through the first two blocks. This involves specifying the content experienced by users adopting the target behaviour.
To do this, the third block lists all the content showed in the target view.

If you are a Segment or an API user, these content elements correspond to the properties of your views and screens. We therefore invite you to fill in and track as many elements as possible in the properties of your views. If you are using the Vespucci SDK, these content correspond to all the elements that make up the user interface and are automatically tracked by Vespucci.

If you are using the Vespucci SDK, these content correspond to all the elements that make up the user interface and are automatically tracked by Vespucci.

The fourth block allows you to specify the value taken by the contents you selected in block 3. When you watched video recordings, identifying content that was the source of a behaviour of interest was relatively easy: you could simply watch the films to identify behaviours that you might not have anticipated yourself. So the editor of our delivery app might be surprised to find that almost no user placed an order when the displayed price was less than 6€. Without videos, you have to rely again on your personal intuition to identify the content behind a certain action. This is a problem because you can't think of everything. That's why the story editor relies on the StoryFinder. The StoryFinder suggests stories you might not have anticipated.


StoryFinder

The StoryFinder uses statistical models to help you identify content of interest. In other words, the StoryFinder helps you complete the third and fourth blocks of the story editor. The StoryFinder can be accessed from the toolbar using the "f(x)" icon. You can also reveal the StoryFinder from the main view by dragging with two fingers on your trackpad or magic mouse.


The StoryFinder is divided into two sections. The first one helps you to identify the content (block 3) likely to influence the described behaviour while the second one helps you to specify the value taken by this content element (block 4).


Behavioural driver

The first section of the StoryFinder lists all content that may influence the described behaviour. For each of these content, our models assign a coefficient. The higher the coefficient, the more likely it is that this element will explain the described behaviour.

Vespucci Advanced Techs

Content Values

The second section of the StoryFinder presents the values taken by the elements listed in the first section of the StoryFinder. It is organised in three frames. The first frame presents the probability of performing the target action knowing the different values taken by the content item.
The second frame presents the time spent by the user on the original view knowing the different values taken by the content item. The third frame presents the path adopted by the user in your product according to the different values taken by the content item.

Vespucci Advanced Techs

Dimensions

Now that you have written your story in the story editor using the insights of the StoryFinder, it is time to visualize it. Visualizing a story is about when, where and in what context the scenario you have described occurs. This visualisation takes place through dimensions. The dimensions can be accessed using the buttons in the left column of Vespucci. There are three of them.

The time dimension allows you to display the occurrence of the story according to the time of day, the day of the week or the month. The lower frame shows the commitment of your users according to these different temporal measures.

Vespucci Advanced Techs

The geographical or places dimension allows you to visualise the geographical distribution of the occurrence of your story.

Vespucci Advanced Techs

The technological dimension allows you to tell your story according to the operating system of your users, the language of their device or the model of their terminal.

Vespucci Advanced Techs