Configuration Social Insights

La configuration de Social Insights dépend du réseau social, car chacun fonctionne différemment :

• Facebook : connectez votre compte, et Piano collecte vos données automatiquement.

• X : envoyez vous-même vos données X à Piano. Il n'y a pas de connexion de compte pour X.

Vous pouvez également, de façon facultative, marquer vos publications avec utm_pid afin de relier vos données sociales à vos données Piano Analytics on-site. Une fois vos données transmises, consultez Lire votre Board Social Insights et le Data Model Social Insights.

Configuration de Facebook

Pour configurer Facebook, connectez votre ou vos comptes Facebook. Contactez votre Account Manager ou l'équipe support ; ils vous enverront un lien qui accorde à Piano la délégation d'accès à votre compte.

Une fois la délégation en place, Social Insights collecte automatiquement vos données Facebook et alimente votre Board. Vous n'avez rien d'autre à envoyer, ni à maintenir.

Configuration de X

X fonctionne différemment de Facebook : il n'y a pas de connexion de compte, et Piano ne peut pas récupérer les données X en votre nom en raison des restrictions de licence de l'API X. Pour intégrer les données X à votre Board, vous envoyez vous-même vos données à Social Insights, selon la méthode ci-dessous. Si vous ne publiez pas sur X, vous pouvez ignorer cette section.

En suivant les instructions ci-dessous, vous pouvez envoyer les données requises au bon endroit. À partir de là, notre data model s'occupe du reste : calculer les métriques et fusionner correctement vos données X avec vos données Facebook et vos autres jeux de données analytics.

L'intégration repose sur deux types de données, les catalogues et les measurements, que vous pouvez envoyer à la fréquence qui vous convient le mieux. Une fois reçues, notre data model traite ces données, calcule les métriques et met toutes les informations obtenues à disposition dans le Board.

Catalogues

Deux catalogues doivent être configurés pour collecter les métadonnées :

Mapping du catalogue : soi_handle

Ce catalogue collecte les métadonnées au niveau du compte.

Exemple de requête :

curl -X POST 'https://analytics-api-eu.piano.io/import/v1/catalogs/batch' \
  -H 'Content-Type: application/x-ndjson' \
  -H 'x-api-key: <API_KEY>' \
  -H 'x-pa-orga-code: <ORGA_CODE>' \
  --data-binary @- <<'EOF'
{
  "import_id": "<HANDLES_CATALOG_ID>",
  "import_keys": {
    "soi_handle_id": "<SOI_HANDLE_ID>"
  },
  "associated_properties": {
    "soi_post_network": "X",
    "soi_handle_name": "<HANDLE_USERNAME>",
    "soi_handle_url": "https://x.com/<HANDLE_USERNAME>"
  }
}
EOF

Mapping du catalogue : soi_post

Ce catalogue collecte les métadonnées au niveau de la publication.

Exemple de requête :

curl -X POST 'https://analytics-api-eu.piano.io/import/v1/catalogs/batch' \
  -H 'Content-Type: application/x-ndjson' \
  -H 'x-api-key: <API_KEY>' \
  -H 'x-pa-orga-code: <ORGA_CODE>' \
  --data-binary @- <<'EOF'
{
  "import_id": "<POSTS_CATALOG_ID>",
  "import_keys": {
    "soi_post_id": "<SOI_POST_ID>"
  },
  "associated_properties": {
    "soi_post_creation_date": "2026-03-20 14:32:10",
    "soi_post_message": "Check our latest race highlights https://example.com/race?utm_pid=<SOI_POST_ID>",
    "soi_post_url": "https://x.com/<HANDLE_USERNAME>/status/<TWEET_ID>"
  }
}
EOF

Measurements

Les measurements portent les données de KPI elles-mêmes. Deux measurements sont à envoyer à intervalles réguliers, et les deux prennent en charge la granularité horaire si vous en avez besoin.

Détail du measurement soi_x_handle

Exemple de requête :

curl -X POST 'https://analytics-api-eu.piano.io/import/v1/measurements/batch' \
  -H 'Content-Type: application/x-ndjson' \
  -H 'x-api-key: <API_KEY>' \
  -H 'x-pa-orga-code: <ORGA_CODE>' \
  --data-binary @- <<'EOF'
{
  "key": "soi_x_handle",
  "period": "<PERIOD>",
  "site_id": <SITE_ID>,
  "values": {
    "followers": 1523
  },
  "properties": {
    "soi_handle_id": "<SOI_HANDLE_ID>"
  }
}
EOF

Détail du measurement soi_x_post

Exemple de requête :

curl -X POST 'https://analytics-api-eu.piano.io/import/v1/measurements/batch' \
  -H 'Content-Type: application/x-ndjson' \
  -H 'x-api-key: <API_KEY>' \
  -H 'x-pa-orga-code: <ORGA_CODE>' \
  --data-binary @- <<'EOF'
{
  "key": "soi_x_post",
  "period": "<PERIOD>",
  "site_id": <SITE_ID>,
  "values": {
    "views": 29435,
    "likes": 26,
    "comments": 13,
    "shares": 3,
    "quotes": 0,
    "bookmarks": 1,
    "link_clicks": 456,
    "profile_clicks": 15,
    "clicks": 471,
    "video_views": 0,
    "posts": 1,
    "playback_start": 0,
    "25_video_play": 0,
    "50_video_play": 0,
    "75_video_play": 0,
    "video_complete": 0
  },
  "properties": {
    "soi_handle_id": "<SOI_HANDLE_ID>",
    "soi_post_id": "<SOI_POST_ID>"
  }
}
EOF

Relier vos données sociales à Piano Analytics (facultatif)

Cette étape est facultative. Elle vous permet de relier vos données Social Insights à vos données Piano Analytics on-site. Sans elle, les deux jeux de données fonctionnent toujours, ils restent simplement séparés.

Social Insights mesure la performance de vos contenus sur les réseaux sociaux : vues, likes, partages et engagement, au niveau de la publication comme du compte. Mais pour les marques, l'histoire ne s'arrête pas à la publication. La vraie valeur réside souvent dans ce qui se passe après le clic : le trafic, l'engagement, les abonnements et les revenus que vos publications sociales génèrent sur votre site.

Piano Analytics mesure déjà toute cette activité on-site. Ce qui manquait, c'était un moyen fiable de relier une visite à la publication exacte qui l'a générée. C'est l'objet de cette section : comment les données Social Insights et Piano Analytics sont combinées grâce à un paramètre UTM dédié, utm_pid, pour vous offrir une vue complète de la performance sociale, de la publication jusqu'à la conversion.

Ce que permet utm_pid

utm_pid est un paramètre UTM de Piano Analytics défini au niveau de la publication. Il vous permet de combiner les données des réseaux sociaux avec les données Piano Analytics, afin de voir la performance d'une publication en parallèle de ce qui s'est passé sur votre site après le clic. Concrètement, utm_pid permet :

• Les visites, les pages vues et l'engagement générés par une publication, un compte ou un réseau spécifique.

• Les conversions, les abonnements et les revenus attribuables à une publication.

• Le comportement on-site des audiences sociales : rebondissent-elles, s'engagent-elles ou convertissent-elles ?

Ajouter utm_pid à vos publications

Pour relier une publication à l'activité on-site qu'elle génère, le paramètre utm_pid doit faire partie du lien sortant au moment où vous publiez. Voici comment procéder :

1. Générez un identifiant unique pour la publication (par exemple, un ID de contenu interne, un ID de CMS ou toute chaîne unique).

2. Ajoutez-le à l'URL de l'article, aux côtés de vos autres paramètres UTM, avant de coller le lien dans votre outil de publication sur les réseaux sociaux :

https://www.example.com/article-slug?utm_source=facebook&utm_medium=social&utm_pid=123

3. Publiez la publication. Social Insights détecte l'utm_pid dans le lien sortant de la publication et l'utilise comme ID de publication (soi_post_id). Les visiteurs qui cliquent transmettent ce même ID à Piano Analytics, ce qui complète le lien entre la publication et leur activité on-site.

Si vous utilisez un outil de publication sociale, le marquage peut être automatisé : configurez les paramètres de suivi des liens de l'outil pour ajouter utm_pid avec une valeur unique à chaque lien publié. Cela supprime l'étape manuelle et garantit la cohérence de votre marquage sur l'ensemble des publications.

Recommandations

• Utilisez un identifiant unique par publication. La valeur utm_pid devient l'ID de publication dans Piano Analytics. Réutiliser la même valeur sur plusieurs publications fusionne leurs données.

• utm_pid fonctionne avec vos paramètres de campagne existants (utm_source, utm_medium, etc.) sans conflit.

• Conservez des valeurs courtes, uniques, compatibles avec les URL et de format cohérent pour éviter les erreurs de marquage.