Alertweet

🇫🇷 Une "mini-app" multi-plateforme basée sur les produits Google Workspace pour recevoir des notifications personnalisées de publications de comptes Twitter (X) selon leurs contenu, dates/heure de publication ou de référence (période mentionnée dans la publication).

🇺🇸/🇬🇧 A cross-platform "mini-app" relying on Google Workspace to get custom notification on Twitter (X) posts from an accounts based on their contents and dates/time of publication or reference (mentionned in the post).

English version below.

🇫🇷 Documentation

ℹ️ Attention à bien vérifier que vous êtes à jour avec le Changelog. Les changements sont indiqués avec une " ⭐ " ici.

⚠️ Toute responsabilité est déclinée par rapport à l'utilisation de cette application, y compris en terme de contenu notifié et de bon fonctionnement. Je ne suis pas responsable du contenu publié sur Twitter (X) que vous cherchez à surveiller.

Ce qu'est Alertweet

Alertweet est un outil développé sur Google Apps script permettant de recevoir des notification personnalisées de posts d'un compte Twitter public. Cela permet de filtrer les tweets selon:

• Des mots-clés,
• La date et l'heure. Soit de publication du tweet, soit d'une date et/ou heure mentionnés dans le tweet.

Les notifications sont envoyées via des évènements Google Calendar. Le paramétrage de l'appli se fait depuis un fichier Google Sheet. La notification arrivera au moment mentionné dans le tweet s'il en est mentionné un; ou directement à sa publication (à 1 minute près) sinon.

L'utilisation des services Google, en plus de leur grande accessibilité (tant au développeur qu'à son public), garantit une totale transparence en matière de code et de sécurité.

Pré-requis

• Un compte Google (si vous disposez de plusieurs comptes Google, n'en utilisez qu'un seul pour cette appli)
• Un ordinateur connecté à internet
• Des connaissances très (très) élémentaires en Google Sheet (/Excel)

Mise en place initiale

Création de l'outil

1. Créer un calendrier Google Calendar et récupérer son ID:
   • dans le menu à gauche, cliquer sur "+" à côté de "Autres Agendas" puis "Créer un agenda". Le nommer et paramétrer puis créer.
   • (en restant) dans les paramètres, choisir l'agenda créé et descendre jusqu'à "ID de l'agenda". Copier l'ID.
2. Créer et nommer un fichier Google Sheet avec le même compte Google que le calendrier. Passer les noms de fonction en anglais (Fichier > Paramètres > Toujours utiliser les noms de fonction en anglais)
3. Créer et nommer 2 feuilles settings et logs
4. Dans la feuille settings:
   • Reproduire selon l'image ci-dessous (la langue n'importe pas, mais l'ordre et le contenu; ex: semaine commençant le Lundi); si.
   • Mettre une case à cocher en B12 (Insertion > case à cocher)
   • Mettre la formule ="'"&substitute(SUBSTITUTE(B2;",";",");"-";"-") en C2 et propager jusqu'à C8.
   • Mettre la formule =if(Not(ISBLANK(B2));MOD(ROW(A2)-1;7);) en D2 et propager jusqu'à D8.
   • ⭐ Mettre la formule ="/"&IF(LEFT(B11;1)="@";RIGHT(B11;LEN(B11)-1);B11) en C11.
   • ⭐ Mettre la formule =IMPORTRANGE("https://docs.google.com/spreadsheets/d/1U2Aw1oGV2b8C4iMrtb4Lkw3XMtgtFwWRH-4zelyNtXU/edit#gid=694530783";"output!A1:B2") en C14.
   • ⭐ Coller l'ID de l'agenda (cf étape 1) en D12.
   • (Optionel) masquer les colonnes C et D (sélectionner les colonnes > clic droit > masquer les colonnes).

5. Dans la feuille logs:
   • Reproduire selon l'image ci-dessous (la langue n'importe pas, mais l'ordre et le contenu; ex: semaine commençant le Lundi); si.
   • (Optionel) figer la ligne 1: clic droit sur le numéro de la ligne (1) > Afficher plus d'options > Figer jusqu'à la ligne 1.

💡 C'est dans cette feuille qu seront inscrits tous les tweets qui ont été retenus après filtrage par mots-clés, date et heure.

6. Créer les macros:

   • Dans Google Sheet: Extensions > Apps Script
   • ⭐ Créer un fichier "Main.gs" et y copier-coller le contenu de Main.gs
   • Créer un fichier pour la détection de date et heure dans le tweet. Y copier-coller le contenu d'un de ces fichiers permettant une détection spéciale pour des comptes Twitter (X) en particulier, ou considérer que tout est en direct (notification reçue moins d'une minute après la publication du tweet) avec le contenu de ce fichier.

7. Accorder les autorisations. Pour la première utilisation, Google va vous demander des autorisations pour accéder à Google Sheet et Calendar.

   • Choisir run dans la liste des fonctions et cliquer sur "Exécuter"
   • Un popup invitant à accorder les autorisations nécessaires apparaît. Accorder les autorisations en se laissant guider. Une fenêtre indiquant que "Google n'a pas validé cette application" apparaît. C'est normal. Cliquer sur "Paramètres avancés", puis "Accéder à Alertweet (non sécurisé)" et enfin "Autoriser". (aucune crainte, Google demande juste l'autorisation d'accéder à vos propres données !)

8. Créer un déclencheur. Cela permettra de faire tourner le code automatiquement sur les serveurs de Google pour s'assurer d'être notifié au bon moment.

   • Aller dans le menu "Déclencheurs" (bouton avec une horloge dans le menu à gauche).
   • Cliquer sur "Ajouter un déclencheur" (bouton bleu en bas à droite)
   • Paramétrer comme ceci: (ou avec vos propres paramètres, même si un intervalle de déclenchement le plus bas assure un meilleur fonctionnement de l'application)
   • Vous recevrez par email chaque semaine un rapport des éventuelles erreurs survenues (les causes sont multiples, par exemple des erreurs de serveurs).

Renseignement du compte à surveiller, mots-clés, dates et heures

Dans la feuille settings, remplir les plages horaires que vous voulez surveiller (les tweets mentionnant ces plages, ou publiés durant celles-ci s'ils n'en mentionnent aucune, seront retenu):

1. En face du jour concerné (B2 à B8), remplir au format [heure du début de la plage]-[heure de la fin de la plage]. Le format d'heure à adopter est [hh]:[mm] avec les heures au format 24h. Pour avoir plusieurs plages horaires sur un même jour de la semaine, les séparer par une virgule sans espace. (ex: 7:00-9:00,17:00-19:00 pour surveiller entre 7:00 et 9:00, puis entre 17:00 et 19:00).
2. Remplir les mots-clés, séparés par des virgules sans espaces. ⚠️ les mots-clés seront recherchés tels quels, donc attention à la casse !
3. Remplir le nom du compte Twitter (X) à surveiller (@...) en B11.

💡 Astuce: Pour ne pas surveiller un jour, laisser la cellule correspondante vide. A l'inverse, pour surveiller la journée complète, écrire 00:00-23:59.

💡 Astuce: Pour choisir correctement les mots-clés, il est conseillé d'aller vérifier les mots employés dans les tweets du compte à surveiller. Si vous n'avez pas de compte Twitter (X), vous pouvez utiliser Twstalker.

⚠️ Décocher la case ON/OFF (B12) arrêtera complètement le fonctionnement de l'appli (OFF) ! Donc aucun tweet ne sera traité, même s'il concerne un moment ultérieur

Limites

• Un seul compte tweeter peut être surveillé à la fois.
• Il y a un risque de manquer des infos lorsque la case ON/OFF est décochée (OFF).
• Changer les périodes de surveillance risque de conduire à manquer des informations concernant les nouvelles périodes si elles ont été postées avant le changement.
• Si plusieurs tweets sont postés dans la même minute (ou dans l'intervalle entre 2 exécution du déclencheurs), il y a un risque de manquer des infos.
• Si le format/synthaxe des tweets postés change, des informations risquent d'être manquées (ex: des mots-clés ne correspondent pas). C'est encore plus vrai en utilisant des fonctions personnalisées pour la date et l'heure (cf partie suivante)

📝 Chaque Tweet devant être notifié (selon les filtres définis) aura la forme d'un évènement Google Calendar dont les jours de début et fin sont soit définis par le tweet, soit le jour même. Pour les heures, le début est soit mentionné dans le tweet, soit l'heure actuelle, tandis que la fin sera l'heure de fin de la période définie dans le Google Sheet au sein de laquelle rentre le tweet en question.

Ex: Période définie pour ce jour (${\color{blue}{28/12/2023}}$): 18:00- ${\color{green}20:00}$.

Tweet:" C9- ${\color{orange}{19h41}}$ - Déviée dir. Hôpitaux Est - Arrêt Part-Dieu Auditorium non desservi - Reprise estimée à 21h.- Embouteillages Rue de Bonnel à Lyon 3ème"

➡️ début de l'évènement: ${\color{blue}{28/12/2023}}-\color{orange}{19:41}$

➡️ fin de l'évènement: ${\color{blue}{28/12/2023}}-\color{green}{20:00}$

Pour les geeks

Vous pouvez choisir de développer vos propres fonctions pour analyser les tweets plus en profondeur en Google Apps Script (Javascript), notament pour détecter des dates et heures. Par exemple, si un service de transport en communs annonce des perturbations à une date ultérieure, il sera plus intéressant de recevoir la notification ultérieurement plutôt qu'au moment du tweet.

• La fonction qui détecte les mots clés prend en entrée un string unique et renvoie un booléen, où true correspond à un mot clé détecté.
• Celle qui récupère les dates dans le corps d'un tweet prend en entrée un string unique et renvoie soit une date (format date de js) ou un array de dates.
• Celle qui récupère les heures dans le corps d'un tweet prend en entrée un string unique et renvoie un array de 2 dates dont la première est la date de début et la seconde celle de fin.
• Si vous souhaitez voir vos fonctions personnalisées intégrées au projet, parlez-en ici !

🇺🇸/🇬🇧 Documentation

ℹ️ Remind to stay updated using the Changelog. Changes from the last release are marked with a " ⭐ " here.

⚠️ Disclaimer: All responsibility is disclaimed regarding the use of this application, including in terms of the notified content and proper functioning. I am not liable for the content published on Twitter (X) that you are seeking to monitor.

What is Alertweet

Alertweet is a tool developed on Google Apps Script that allows receiving personalized notifications for posts from a public Twitter account. This enables filtering tweets based on:

• Keywords,
• Date and time, either of tweet publication or a date and/or hour mentioned in the tweet.

Notifications are sent via Google Calendar events. The application configuration is done through a Google Sheet file. The notification will be sent at the moment mentionned in tweet if there is on mentionned; or else directly after it is posted (within 1 minute).

The use of Google services, in addition to their broad accessibility (both for developers and their audience), ensures complete transparency in terms of code and security.

Prerequisites

• A Google account (if you have multiple Google accounts, use only one for this app)
• A computer connected to the internet
• Very (very) basic knowledge of Google Sheet/Excel

Initial Setup

Creating the Tool

1. Create a Google Calendar and retrieve its ID:
   • In the left menu, click on "+" next to "Other Calendars," then "Create Calendar." Name it and set it up, then create.
   • (While still) in the settings, choose the created calendar and scroll down to "Calendar ID." Copy the ID.
2. Create and name a Google Sheet file with the same Google account as the calendar. If you're not using Google Sheet in English language, set the function names to English (File > Settings > Always use English function names).
3. Create and name 2 sheets settings and logs
4. In the settings sheet:
   • Replicate according to the image below (language doesn't matter, but order and content do; e.g., week starting on Monday).
   • Insert a checkbox in B12 (Insert > Checkbox)
   • Write the formula ="'"&substitute(SUBSTITUTE(B2;",";",");"-";"-") in C2 and fill it down to C8.
   • Write the formula =if(Not(ISBLANK(B2));MOD(ROW(A2)-1;7);) in D2 and fill it down to D8.
   • ⭐ Write the formula ="/"&IF(LEFT(B11;1)="@";RIGHT(B11;LEN(B11)-1);B11) in C11.
   • ⭐ Write the formula =IMPORTRANGE("https://docs.google.com/spreadsheets/d/1U2Aw1oGV2b8C4iMrtb4Lkw3XMtgtFwWRH-4zelyNtXU/edit#gid=694530783";"output!A1:B2") in C14.
   • ⭐ Paste the calendar ID (step 1) into D12.
   • (Optional) hide columns C and D (select columns > right-click > hide columns).

5. In the logs sheet:
   • Replicate according to the image below (language doesn't matter, but order and content do).
   • (Optional) freeze row 1: right-click on the row number (1) > Show more options > Freeze up to row 1.

💡 This sheet will record all tweets that have been retained after filtering by keywords, date, and time.

6. Create the macros:

   • In Google Sheet: Extensions > Apps Script
   • ⭐ Create a file "Main.gs" and copy-paste the content of Main.gs
   • Create a file for date and time detection in the tweet. Copy-paste the content of one of these files that allows special detection for specific Twitter accounts (X), or consider everything is live (notification received less than a minute after the publication of the tweet) with the content of this file.

7. Grant permissions. For the first use, Google will ask for permissions to access Google Sheet and Calendar.

   • Choose run from the list of functions and click "Run"
   • A popup inviting you to grant the necessary permissions will appear. Grant the permissions by following the instructions. A window indicating that "Google has not verified this app" will appear. This is normal. Click "Advanced settings," then "Access Alertweet (not secure)" and finally "Authorize." (no worries, Google is just asking for permission to access your own data!)

8. Create a trigger. This will allow the code to run automatically on Google's servers to ensure you are notified at the right time.

   • Go to the "Triggers" menu (clock button in the left menu).
   • Click on "Add Trigger" (blue button at the bottom right)
   • Set it up like this: (or with your own settings, although a lower trigger interval ensures better application performance)
   • You will receive a weekly email report of any errors that may have occurred (causes are diverse, such as server errors).

Providing Information for the monitored Account, keywords, dates and times

In the settings sheet, fill in the time ranges you want to monitor (tweets mentioning these times, or published during them if not mentioned, will be retained):

1. Across from the relevant day (B2 to B8), fill in the format [start time of the range]-[end time of the range]. The time format to adopt is [hh]:[mm] with 24-hour format. To have multiple time ranges on the same day of the week, separate them with a comma without space. (e.g., 7:00-9:00,17:00-19:00 to monitor between 7:00 and 9:00, then between 17:00 and 19:00).
2. Fill in the keywords, separated by commas without spaces. ⚠️ keywords will be searched as they are written there, so be careful with case sensitivity!
3. Fill in the name of the Twitter account (X) to monitor (@...) in B11.

💡 Tip: To avoid monitoring a day, leave the corresponding cell empty. To monitor the entire day, write 00:00-23:59.

💡 Tip: To choose keywords correctly, it is recommended to check the words used in the tweets of the account to be monitored. If you don't have a Twitter account (X), you can use Twstalker.

⚠️ Unchecking the ON/OFF box (B12) will completely stop the application (OFF)! So, no tweets will be processed, even if they concern a later time.

Limitations

• Only one Twitter account can be monitored at a time.
• There is a risk of missing information when the ON/OFF checkbox is unchecked (OFF).
• Changing monitoring periods may lead to missing information about new periods if they were posted before the change.
• There is a risk of missing information if several tweets are published within the same minute (or during the interval between two runs of the code scheduled by the trigger)
• If the format/syntax of posted tweets changes, information may be missed (e.g., keywords not matching). This is even more true when using custom functions for date and time (see next section).

📝 Each Tweet to be notified (according to the filters defined) will take the form of a Google Calendar event whose start and end days are either defined by the tweet, or on the day itself. For times, the start time is either mentioned in the tweet or the current time, while the end time will be the end time of the period defined in the Google Sheet in which the tweet in question falls.

E.g. Defined period for the current day (${\color{blue}{28/12/2023}}$): 18:00- ${\color{green}20:00}$.

Tweet: "⚠️SERVICE ALERT - 1 & 5 (Bath)⚠️ The following services will not operate: 🚌 1 - ${\color{orange}{16:26}}$ Bath Bus Station to Southdown (due 17:13) 🚌 5 - 18:26 Bath Bus Station to Whiteway Circle (due 19:16) We apologise for any inconvenience caused."

➡️Start of the event: ${\color{blue}{28/12/2023}}-{\color{orange}{16:26}}$

➡️End of the event: ${\color{blue}{28/12/2023}}-{\color{green}20:00}$

For Geeks

You can choose to develop your own functions to analyze tweets more deeply in Google Apps Script (JavaScript), especially for detecting dates and times. For example, if a public transport service announces disruptions at a later date, it would be more interesting to receive the notification later than at the time of the tweet.

• The function that detects keywords takes a unique string as input and returns a boolean, where true corresponds to a detected keyword.
• The one that retrieves dates from the body of a tweet takes a unique string as input and returns either a date (JavaScript date format) or an array of dates.
• The one that retrieves hours from the body of a tweet takes a unique string as input and returns an array of 2 dates, where the first is the start date and the second is the end date.
• If you want to see your custom functions integrated into the project, discuss it here!