dacc.md

DACC

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 :

On the developpement 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 accoun 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 consomation	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 resultat 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 resultat 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	Resultat 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
Tentatitve 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
Consomation	'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

// 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 consomation 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'utilsteur 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 auncune 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 :

{
  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
• 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.

    "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.

node srcipts/server.js

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

    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)

  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 genereated events in the db com-grandlyon-ecolyo-usageevent

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

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.

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

{
  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.

Errors

More here in 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 :

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