Forem: Sencrop

Inception coding: write code to analyze your code (in Typescript)

Nicolas Delperdange — Thu, 10 Dec 2020 09:32:18 +0000

If you want to get some statistics about code usage or generate some documentation about it, you are it the right place !

Let's investigate how to analyze your code in this article.

Better than using regex which is a sequence of characters comparison, we will explain how you can achieve this more efficiently thanks to an AST tree which uses syntactical analysis.

We will develop this around our own usecase: find all calls to an analytic service and create a markdown report (which will be used by our product team).

This work is inspired by the work made by nfroidure in jsarch

Step 0: Package installation

Here is all package we will use in this article:

npm install -D ts-node @babel/parser ast-types glob-promise json2md lodash

Our script will be written in typescript and will be launched by a npm command, so we have to add it in the script section of our package.json:

"scripts": {
    "analytics": "ts-node -O '{\"module\":\"commonjs\"}' bin/parseAnalytics.ts"
}

ts-node is needed to convert our typescript script, and a little option because we will use import statements.

Step 1: Grab files

The first step is pretty simple. To optimize and not reading all files in our project, we will generate a list of files to visit.
To do that, we will use node-glob.

In our case, we want to visit javascript or typescript files in our /src folder.

const filesPaths = await glob("src/**/*.{ts,js}", {
    cwd: process.cwd(),
    dot: true,
    nodir: true,
    absolute: true,
});

process.cwd() returns the current directory, since we are launching with npm, it is our project folder.

Step 2: File content to AST

To be able to analyze our code, we will generate an AST tree from our code.

Quickly, here is the definition of an AST tree:

An abstract syntax tree (AST) is a tree representation of the abstract syntactic structure of source code written in a programming language.

So with our files list, we read their content with the fs library.

const content = fs.readFileSync(filePath, "utf-8");

Then, we create our AST with the help of babel-parser (you can add plugins depending of your needs):

const ast = parse(content, {
    sourceType: "module",
    plugins: ["typescript", "jsx", "classProperties"],
});

Step 3: Visit AST

In this step, we visit our AST tree to convert it into a easier structure (in our case it will be an array with all analytic calls, at the moment it just contains the name of the event).
There are a lot of visit functions available (more or less one per AST type), so we first need to find which visit function is the most appropriate.

To do that, copy-paste one example of file you want to visit in an AST tree explorer, for example ast-explorer.

In our case, our call that we want to analyze is a ExpressionStatement:

Analytics.track({
    event: 'This is a event',
    properties: {
        device: 1
    },
});

So we will implement the visitExpressionStatement:

const analyticsCalls = [];
 visit(ast, {
      visitExpressionStatement: function (path) {
          // Implement your logic here to grab correct parameter
          // In our case, we retrieve the event sended
          if (path.value.expression.callee?.property?.name === 'track') {
            const analyticsParams = path.value.expression.arguments[0];
            const analyticEventName = analyticsParams.properties.find(
              (prop) => prop.key.name === 'event',
            );
            analyticsCalls.push({
              event: analyticEventName?.value?.value || 'N/D',
            });
          }
          this.traverse(path);
      },
 });

In the visit function, we explore the properties from the AST node and create an object (with the analytic event name) to push it into an array for the next step.
This is the hardest step, but the AST explorer will help you find the correct visit function and the properties of each AST node.

The traverse function must be called to continue to explore the AST until the end of it.

Step 4: Generate your markdown

Finally, we use the array that we have generated before to create a markdown, by using json2md package:

json2md([
    { h1: 'Analytics' },
    {
      table: {
        headers: ['Event'],
        rows: analyticsCalls.map((analyticsCall) => ({
          Event: analyticsCall.event,
        })),
      },
    },
]);

Final script

Here is a recap of the script:

import { parse } from '@babel/parser';
import { visit } from 'ast-types';
import fs from 'fs';
import glob from 'glob-promise';
import json2md from 'json2md';
import { flatten } from 'lodash';

type AnalyticsElement = {
  event: string;
};

async function parseAnalytics() {
  const cwd = process.cwd();

  const filesPaths: string[] = await glob('src/**/*.{ts,js}', {
    cwd,
    dot: true,
    nodir: true,
    absolute: true,
  });

  const analyticsCalls = await Promise.all(
    filesPaths.map((file) => extractAnalytics(file)),
  );

  const markdownContent = generateMarkdown(flatten(analyticsCalls));

  fs.truncateSync('ANALYTICS.md');
  fs.writeFileSync('ANALYTICS.md', markdownContent);
}

async function extractAnalytics(filePath: string): Promise<AnalyticsElement[]> {
  const content = fs.readFileSync(filePath, 'utf-8');

  const ast = parse(content, {
    sourceType: 'module',
    plugins: ['typescript', 'jsx', 'classProperties'],
  });

  const analyticsCalls: AnalyticsElement[] = [];

  visit(ast, {
    visitExpressionStatement: function (path) {
      if (path.value.expression.callee?.property?.name === 'track') {
        const analyticsParams = path.value.expression.arguments[0];
        const analyticEventName = analyticsParams.properties.find(
          (prop) => prop.key.name === 'event',
        );
        analyticsCalls.push({
          event: analyticEventName?.value?.value || 'N/D',
        });
      }
      this.traverse(path);
    },
  });

  return analyticsCalls;
}

function generateMarkdown(analyticsCalls: AnalyticsElement[]): string {
  return json2md([
    { h1: 'Analytics' },
    {
      table: {
        headers: ['Event'],
        rows: analyticsCalls.map((analyticsCall) => ({
          Event: analyticsCall.event,
        })),
      },
    },
  ]);
}

parseAnalytics();

Conclusion

You should now be able to adapt this usecase to suit your needs, and we hope you learnt things with this article!
Thanks for reading!

Authors

🔔You've got a notification🔔

Nicolas Delperdange — Fri, 27 Nov 2020 09:52:56 +0000

At Sencrop, we deep dived into push notifications mechanism on mobile devices, and we would like to share our findings with you!

What is a push notification?

When people talk about push notifications, it often refers to a message that is shown in the notification tray of a mobile device, like this one:

But push notification is a way bigger concept!

Some type definition first 😁

Push notification is a client-server communication mode in which the dialogue is initiated by the server.

This technique is therefore opposed to the “classic” functioning of web transactions where the customer opens a dialogue and pulls information towards him.

Push notifications are a great way to contact users because they are displayed very closely to them and they are hard to miss.

That is why they are much appreciated by product teams, in order to transmit transactional notifications (such as alerts, ...) but also by marketing teams (to promote commercial operations for example).

However, be careful to not betray the trust of users by sending them too many unwanted notifications.

Payload: Notification vs Data

There are 2 kinds of push notifications payload:

Notification messages, sometimes thought of as display messages. These are handled automatically by the underlying SDK (FCM for example). They are easy-to-use because it self-contains everything to be able to show a message on the device.
Data messages, which are handled by the client app. A specific logic must be written in the app, so they are less straight forward but it allows to do custom tasks (like fetching more data from a remote server, checking some conditions, triggering alerts, ...).

Technical notes:

A message can have both fields (notification and data). In this case, a message will be displayed to the user, and the data payload will be transmitted (to be handled in background by the app).
A notification message must use the predefined keys to be able to create a notification in the system tray of the user's device (like the title, body, the action when the user clicks on the notification, ...).

How does it works?

A push notification will go through multiple mechanisms before showing a message on the user's device (or triggering a background action).

A push notification is triggered from a trusted environnement (at Sencrop, directly from our server or from Intercom) that contacts Push Notifications Servers (Apple Push Notification server for iOS devices or Firebase Cloud Messaging server for Android devices).

We specify trusted environnement, because this server must provide the APN certificat or Firebase key to be able to contact push servers.

To be able to trigger a push notification, the server must first have a token that identified the user's device (or user's devices).

This token will be generated when the user has authorized push notifications on his device and after this will be sent to our server to be stored (in a database for example) for future use.

Technical notes:

There are 2 types of token, APN (Apple - iOS) and FCM (Google - Android) tokens.
Intercom directly contacts APN Server and FCM Server to send a push notification (so we must send the APN token to Intercom for iOS devices, and FCM token for Android devices)
For our own server, we have decided to use Firebase only to send push notifications. This way Firebase contacts APN servers to send push notifications on iOS. We convert the APN token (generated on iOS devices) to a FCM token (thanks to the Firebase SDK) and this way we only have FCM tokens in our database and can contact FCM server only.

Authorization

Push notification authorization can be a bit tricky and is different on iOS and Android devices.

🤖 Android

On Android, the application declares the permission directly in its manifest (a configuration file), and the users will automatically authorize the application to push notifications when the application is installed from the store.

🍏 iOS

On iOS, the permission is not automatically delivered when the app is installed.

The application must trigger a pop-up, so users can decide if they authorizes or not the app to send push notification.

This pop-up must be triggered from code by calling a specific iOS API.

It can be:

Directly on the application code (for example, when the user clicks on a button)
With the help of third-party (for example from an Intercom carousel, that could help explaining why we need to authorize push notifications).

Technical notes:

It is recommended to not show the authorization pop-up directly without explanation, at the application start for example. Because the user could decline it and it is hard to revert this decision (must be a manual action from the user in application settings) and your notifications will be just denied.
Before iOS 12, the user could go to the settings of the application and manually authorize the application. After iOS 12, it is not possible anymore, and the user can only remove the authorization if already provided.

To sum up with an image:

Deep links

A deep link is a way to link directly to a specific location inside of a mobile app, rather than simply launching the app (or to do a specific action by the app).

Here are examples of deep links:

To be able to open the deep link, the application must register to the device that the application can handle those links.

This is done directly through configuration of the application (in the manifest.xml on Android and Universal link configuration on iOs, see links in further readings).

The app will be opened when the user clicks on the link (or if the link is in the click action of the notification), and the link will be transmitted to the app to be handled (so the app can parse the link and open the correct view, or do a specific action).

Http scheme and custom scheme

Registering the http(s) scheme, allows the application to open url usually destined to the browser. On mobile devices, it will show a pop-up to users asking if they want to open the browser or the app.

By using a custom scheme, like app://, the app will be directly opened because it is normally the only one which has registered this scheme with this package name.

Technical Notes:

It is possible to open directly the app with a http scheme but it requires additional configuration: https://developer.android.com/training/app-links/verify-site-associations

Conclusion

You now know the basics to be able to trigger push notifications and show messages on your users’ devices. Let’s try it by yourself!

Forem: Sencrop

Inception coding: write code to analyze your code (in Typescript)

Step 0: Package installation

Step 1: Grab files

Step 2: File content to AST

Step 3: Visit AST

Step 4: Generate your markdown

Final script

Conclusion

Authors

🔔You've got a notification🔔

What is a push notification?

Payload: Notification vs Data

How does it works?

Authorization

🤖 Android

🍏 iOS

Deep links

Http scheme and custom scheme

Conclusion

Further readings

Authors