dacc.md

# DACC (Data Aggregator Cross Cozy)

What is DACC ? A cozy blackbox where apps can send data in order to be anonymised and aggregate to provide usage stats.

## Infrastructure workflow

We have two environments, a dev one and a production. Both of them look like the following schema : 

![dacc](/img/architecture/dacc.png)

On the development env, the 'cozy env' refers to our 'Alpha' VM.

## Service

There is a service named `aggregatorUsageEvent`, running on a daily basis, sending pre-processed data to cozy. This service is responsible for parsing traced events store in database and send them to cozy. 

The service is configured to run every night at **01:00AM**.

## Usage events

This section explains how the application is tracking usage events. Here are the main step:

- All events are stored during the use of the application in the doctype **com.grandlyon.ecolyo.usageevents**
- A service is responsible of the aggregation of these events to create ANONYMIZED indicators. These indicators are then sent to a remote docType.

| Title | Tech name | target | context | startDate | result | trigger | Cozy Dacc Name | 
| --- | --- | --- | --- | --- | --- | --- | --- |
| Changement d'action dans un challenge | ActionChangeEvent | Id de l'action | Id du challenge en cours | --- | --- | Chaque appui sur le bouton `selectEcogesture` dans le `ActionCard` | navigation-action-daily |
| Validation de la fin d'une action | ActionEndEvent | Id de l'ecogeste | Id du challenge en cours | Date de début de l'action | --- | Lors de l'appui sur le bouton de fin d'action | event-duration |
| Connexion d'un utilisateur | ConnectionEvent | --- | Navigateur utilisé | --- | Si c'est la première connexion `firstConnection` est stocké | A chaque chargement de l'application | connection-count-daily |
| Connecteur Classique | KonnectorConnectEvent | Slug du connecteur | --- | --- | Success ou error | Le succès dans le cas ou on a la pop-up 'félicitation', le 'error' en cas d'erreur de quelque type que ce soit (catch) | konnector-event-daily |
| Connecteur Oauth (enedis, GRDF) | KonnectorConnectEvent | Slug du connecteur | --- | --- | Success ou error | Le succès dans le cas ou on a la pop-up 'félicitation', le 'error' dans le cas ou aucun account n'est créé | konnector-event-daily |
| Refresh manuel du connecteur | KonnectorRefreshEvent | Slug du connecteur | --- | --- | Success ou error. Le succès est set quand l'état du trigger est a 'done' | Lors de l'appuie sur le bouton 'mettre a jour' | konnector-event-daily |
| Navigation utilisateur dans l'application | NavigationEvent | Nom de la page ( voir 1. en dessous ) | --- | --- | --- | --- | navigation-count-daily |
| Comparaison de consommation | ConsumptionCompareEvent | timestep in lowercase | fluid type in lowercase | --- | --- | --- | navigation-action-daily |
| Changement de pas de temps | ConsumptionChangeTimeStepEvent | timestep in lowercase | fluid type | --- | --- | --- | navigation-action-daily |
| Lancement d'un challenge | ChallengeLaunchEvent | challenge id | --- | --- | --- | Appuie sur le bouton de lancement de challenge dans le cas on la pop-up 'pas de fluid' ne s'affiche pas | event-duration |
| Title | Tech name | target | context | startDate | result | trigger | Cozy Dacc Name | 
| Fin d'un challenge | ChallengeEndEvent | challenge id | --- | date de début du challenge | --- | Lors de la visualisation d'un challenge, si le résultat de celui-ci est a 'fini' on enregistre l'événement | event-duration |
| Début d'un duel | DuelLaunchEvent | duel id | challenge id | --- | --- | Appuie sur le bouton de lancement d'un duel | event-duration |
| Fin d'un duel | DuelEndEvent | duel id | --- | challenge start date | 'win' or 'loss' | Lors de la visualisation d'un duel, si le résultat de celui-ci est a 'fini' on enregistre l'événement | event-duration |
| Fin d'un quiz | QuizEndEvent | Quiz id | Challenge Id | Quiz start date | Résultat du quiz (de 0 a 5) | Lors de la pop-up de résultat | event-duration |
| Fin d'une exploration | ExplorationEndEvent | exploration id | challenge id | exploration start date | --- | Lors de la pop-up de résultat | event-duration |
| Changement de choix d'action | ActionChangeEvent | action id | current challenge id | --- | --- | Lors du click sur le bouton d'acceptation de l'action | navigation-action-daily |
| Fin d'une action | ActionEndEvent | action id | current challenge id | action start date | --- | Lors du click sur le bouton de validation de la page ActionDone | event-duration |
| Complétion d'un nouveau profile | ProfileSetEvent | --- | --- | --- | --- | Lors de l'affichage de la page de félicitation profileTypeFinished | navigation-action-daily |
| Consultation du nouveau bilan mensuel | ReportFromEvent | --- | 'analysis' | --- | 1 | Lorsque l'utilisateur consulte sa page analyse quand la notification est activée | summary-subscription-monthly |
| Tentative de connexion à un connecteur (initialisation)| KonnectorAttemptEvent | Slug du connecteur | --- | --- | 'success or error' | Lorsque l'utilisateur clique sur le bouton de connexion. Lorsque la connexion est réussie, et que l'utilisateur clique sur OK dans la modale le *result* est passé à 'success'  | konnector-attempts-monthly |

1. Nom de la page, différents cas existant

| Page | target | Trigger |
| --- | --- | --- |
| Consommation | 'electricity', 'gas', 'eau', 'multifluid' | Click sur un des fluids dans la bar navigation |
| FAQ | 'faq' | Click sur la card de consultation |
| CGU | 'legalNotice' | Click sur la card de Legal Notice |
| Autres | 'consumption' 'challenges' 'ecogestures' 'analysis' 'options' | Click dans la navbar |

## Indicators

!!! warning "note"
    All indicators are only sent if a user validate first version of CGU, the one containing dacc validation

### Monthly Indicators

All monthly indicators call can be found after this comment on the code

```js
// Monthly events
```

| Indicator | Trigger | value |
| --- | --- | --- |
| consumption-variation-monthly | Tous les mois si l'utilisateur a été connecté au moins une fois dans le mois | La variation de consommation par type de fluide. Les paramètres différents sont le type de profil ainsi que le nombre de mois entre la première connexion de l'utilisateur et le moment où est remonté l'indicateur (seniority) |
| summary-subscription-monthly | Tous les mois si un utilisateur a souscrit a la newsletter ou c'est désabonné | 1 si l’utilisateur est inscrit sinon 0 |
| fluid-data-granularity-monthly | Tous les mois sans condition | 1 si l'utilisateur possède de la donnée a la demi heure sur le mois. Sinon 0 |
| connection-count-monthly | Tous les mois | Le nombre de jour unique de connexion sur le mois précédent. Sinon aucune connexion, 0 |
| profile-count-monthly | Tous les mois si le profil a été complété au moins une fois | Le nombre de fois ou le profile a été complété |
| konnector-attempts-monthly | Tous les mois, le nombre de tentative de connexion pour connecter un connecteur la première fois. Une fois la connexion réussie, l'indicateur remonte true dans le groupe "success". L'indicateur ne remonte ensuite plus pour cet utilisateur car il aura déjà réussi à se connecter une première fois. | Le nombre total de tentatives |

### Daily Indicators

The daily process get all events of previous day and process them in the following indicators

| Indicator | Trigger | value |
| --- | --- | --- |
| connection-count-daily | Tous les jours | Nombre de connexion. Celle-ci sont catégorisé par type (mobile ou desktop), basé sur le navigateur de l'utilisateur. (les tablettes sont comptées comme des mobiles) |
| konnector-event-daily | Tous les jours | Nombre d'essai. Ils sont catégorisé par type de connecteur, refresh/success et le status (error ou success) |
| konnector-connected-daily | Tous les jours | La valeur est 1. Les valeurs sont catégorisées par type de fluide (electricity / electricity:water ...) |
| navigation-count-daily | Tous les jours | nombre de page visualisé par type de page |
| challenge-launch-daily | Tous les jours | Nombre de défis lancés lors d'un challenge  |
| session-duration | Tous les jours | Durée de la session en secondes |
| navigation-action-daily | Tous les jours | Nombre d'action sur une page donnée. Exemple sur la consomation on trace les changements de pas de temps sur chaque graph. |
| event-duration | Tous les jours | Durée entre deux événements: 
1ere session et premier challenge / début de challenge et fin de challenge / début d'exploration et fin d'exploration / début d'action et fin d'action / début de duel et fin de duel |
| quiz-stars | Tous les jours | Nombre d'étoiles obtenu a la fin d'un quiz |

## Information sending

### Format

All indicator are post to a remote doctype, which will allow the application to read a defined external API. This doctype is created by Cozy itself.
The structure to send is the following :

```ts
{
  createdBy: string
  measureName: string
  startDate: string
  value: number | null
  group1?: object
  group2?: object
  group3?: object
}
```

with:

- *createdBy*: contains "ecolyo" value.
- *startDate*: used to defined the start date of the indicator
- *value*: contains a value relevant to the defined indicator (example: number of page viewed on a day).
- *groups*: contains all attributes defining a indicator. Please refer to [indicators definition](https://stats.cozycloud.cc/question#eyJkYXRhc2V0X3F1ZXJ5Ijp7ImRhdGFiYXNlIjo0LCJxdWVyeSI6eyJzb3VyY2UtdGFibGUiOjh9LCJ0eXBlIjoicXVlcnkifSwiZGlzcGxheSI6InRhYmxlIiwidmlzdWFsaXphdGlvbl9zZXR0aW5ncyI6e319)
- *mesureName*: contains one of the following value
  
| ENUM | value |
| --- | --- |
| CONNECTION_COUNT_DAILY  | connection-count-daily |
| KONNECTOR_EVENT_DAILY   | konnector-event-daily |
| KONNECTOR_CONNECTED_PER_DAY   | konnector-connected-daily |
| NAVIGATION_COUNT_DAILY   | navigation-count-daily |
| CHALLENGE_LAUNCH_EVENT_DAILY   | challenge-launch-daily |
| CONSUMPTION_VARIATION_MONTHLY   | consumption-variation-monthly |
| SESSION_DURATION   | session-duration |
| NAVIGATION_ACTION_DAILY   | navigation-action-daily |
| EVENT_DURATION   | event-duration |
| QUIZ_STARS    | quiz-stars |
| SUMMARY_SUBSCRIPTION_MONTHLY  | summary-subscription-monthly |
| FLUID_DATA_GRANULARITY    | fluid-data-granularity-monthly |
| CONNECTION_COUNT_MONTHLY    | connection-count-monthly |
| PROFILE_COUNT_MONTHLY    | profile-count-monthly |
| KONNECTOR_ATTEMPTS_MONTHLY    | konnector-attempts-monthly |

### Environments

There is two remote doctypes pointing to two different mode. `dacc-dev` is used on alpha.

```json
    "dacc": {
      "type": "cc.cozycloud.dacc",
      "verbs": ["ALL"]
    },
    "dacc-dev": {
      "type": "cc.cozycloud.dacc.dev",
      "verbs": ["ALL"]
    },
```

## How to local test ?

First you need to modify the service in order to be able to see data in local :

- Run a local server that will listen and log events.

```sh
node srcipts/server.js
```

- Edit dacc URL (line 67) to send requests to your local server at `http://localhost:8081`

```js
    await client
      .getStackClient()
      .fetchJSON(
        'POST',
        environments.isProduction()
          ? '/remote/cc.cozycloud.daccv_2'
          : 'http://localhost:8081',
        {
          data: JSON.stringify(indicator),
        }
      )
```

- For **monthly indicators**, remove date protection (ligne 1100)

```js
  if (
    profile
    // &&
    // DateTime.local()
    //   .setZone('utc', {
    //     keepLocalTime: true,
    //   })
    //   .startOf('day').day === profile.monthlyAnalysisDate.day
  ) {
```

- Generate usage events by navigating through the app

You will be able to see previous events and freshly generated events in the db `com-grandlyon-ecolyo-usageevent`

:warning: because the cron run every day at 2am, it will take events from the day before. So if you want to test specific usage, you will have to edit the `eventDate` of events you want to send.

- Then you are finally ready to test ! Just run the following :

*If aggregatorUsageEvents changed:*

```sh
yarn build-dev:browser && yarn run cozy-konnector-dev -m ./manifest.webapp ./build/services/aggregatorUsageEvents/ecolyo.js
```

*To save time, when running multiple times and if aggregatorUsageEvents didn't change, you don't have to build.*

```sh
yarn run cozy-konnector-dev -m ./manifest.webapp ./build/services/aggregatorUsageEvents/ecolyo.js
```

- You should see sent indicators in the logs of your local server

```json
{
  "data": {"createdBy":"ecolyo","measureName":"connection-count-monthly","startDate":"2021-12-09","value":3}
}
{
  "data": {"createdBy":"ecolyo","measureName":"connection-count-monthly","startDate":"2021-12-09","value":3}
}
```

## How to add new indicator ?

You have to reach cozy and discuss with them about new indicators. They will implement it for `dacc-dev` and `dacc` and you will be able to test it on alpha env. Remember you will need **at least 5 data** of each type to see it in metabase.

## Visualisation

All the data aggregated in the dacc can be visualized with a *Metabase* website hosted by [cozy](https://stats.cozycloud.cc/).

## Errors

More here in [DJU](/ecolyo/functionalities/profile_type/#dju).

If there is an authentication error, the api will returns an error in html format to cozy, so you'll get from cozy an error 502 as following, because cozy expects a json response :

```json
{
  "status": "502",
  "title": "Bad Gateway",
  "detail": "the content-type for the response is not authorized",
  "source": {}
}
```