DEV Community: Osada Vidath

How to build an eCommerce website and integrating Email notification only using open source tools

Osada Vidath — Thu, 01 Feb 2024 15:58:06 +0000

TL;DR

In this tutorial, you’ll learn how to build an eCommerce store that you can fully customize and even prepare the ground for sending transactional notifications and messages to buyers.

As a developer, knowing how to build an eCommerce website with code is a practical and valuable skill. It opens up job opportunities, lets you work on real projects, and adds versatility to your skill set. Plus, in the world of web development, eCommerce is a stable and growing industry. So, whether you're into building your own projects, collaborating with others, or just want to stay in the loop with tech trends, diving into eCommerce coding can be a smart move.

1st rule in software development: Don't reinvent the wheel unless you really have to. It's fine to recreate something for learning or business purposes, BUT if something is not your core competency, pick a ready-to-use solution. This saves nerves, time, and money.

Open source is the developer’s way of giving back to humanity, so in this tutorial, we are going to use it. Everyone loves simple food recipes that don’t require tons of different ingredients, and in this meal, we are going to include ONLY TWO because that’s all we need.

Medusa is an open source, headless ecommerce engine that prides itself as an alternative to Shopify. It’s built on Node.js with modification in mind, Medusa is composed of three parts:

Headless commerce: The repository that exposes the REST API

Admin panel: Developers can use the Medusa admin panel to customize and manage their store functionalities

Frontend: You can develop the frontend with Next.js, a static site generator like Gatsby, or any other framework

You can learn more about Medusa by checking their GitHub repository.

The BIGGEST MISTAKE developers make is not thinking far ahead and plan for future potential needs. That is the main difference between software developers and software engineers. Building notifications infrastructure / systems is not even a real thought initially. It always starts with something small. Sending an email to confirm the purchase, sending a push notification about a sale going live, or even just an SMS with a confirmation code to authenticate the user in the registration stage. Very soon, it becomes a nightmare to build, maintain and oversee, and once the store takes off and requires to handle higher scale, the real pain come knocking on the door (It calls “Refactoring”) which in polite terminology means: “The code is crap and cannot be maintained so we need to rewrite the whole thing”.

So I came across a DevTool that does just that! An open-source READY-TO-INTEGRATE notifications infrastructure!

Honestly, I feel that sharing such a tool is almost like sharing a cheat code and competitive advantage, but they just won Producthunt’s Golden Kitty Award, so anyway, they are going to be on everyone's radar soon, so there is no real point in gatekeeping this. Enjoy!

Novu is the one tool you need for ALL of your notification needs in the present and the future.

All that is required from you is:

Create an account
Pick the channels you wish to communicate with your customers (Email, SMS, WhatsApp, etc.)
Connect your providers (SendGrid, Twillio, FCM, etc.)
Build your tailored notification workflow (Or just use their pre-made templates)
Add the code snippet to your Backend to call Novu’s API once an event accrued

And that’s it!

Anyway, at the end of this guide, you will have a clear idea about how to use Novu and how to implement it with your Medusa eCommerce store.

Are you not really a tutorial person? Or maybe just want a shortcut? I've got you covered.

You can obtain the source code for this tutorial on this GitHub repository.****

Prerequisites

You’re going to use TypeScript throughout this project, for that you need to have Node JS installed on your local computer. If you don’t already have it, you can download it from the official Node JS website.

It is recommended to have a preliminary idea about basic JavaScript concepts to make navigating through this tutorial easier but feel free to follow along even if you don’t have much experience.

Configuring Databases

To properly use Medusa and its notification features, you need to utilize two databases, namely PostgreSQL and Redis. Let’s discuss about installing each of those databases in this section.

Configuring Redis

If you’re using Linux or Mac, the process is fairly easier, you can just install Redis in your local computer following the instructions from Redis official documentation.

But if you are using windows, things are little more completed, you need to have WSL2 installed in order to use Redis locally. You can find instructions for that here.

Also if you don’t want to install Redis locally, you can deploy a small but free Redis instance in their free managed cloud platform as well.

Configuring PostgreSQL

PostgreSQL is the main database that is used by Medusa. Installing Postgres is fairly straightforward. You can download the relevant installer that matches your OS from their official website.

Once both of the databases are correctly configured, you can move on to the next step.

Configuring Medusa

Installing Medusa

To test Novu integration, you need a Medusa instance up and running on your local computer. A Medusa instance consists of 3 parts, you can install and setup all three of them all at once with one single command by using the “create-medusa-app” utility provided by Medusa.

To create a Medusa store, open your terminal at the location of your choice and run the following command.

npx create-medusa-app@latest

Once you run this command on your terminal, you will be presented with a series of questions, make sure to enter your PostgreSQL database’s connection information correctly and choose to install the Next.js starter storefront (You won’t be touching its code but it would be needed for testing the integration)

You can find more information about “create-medusa-app” in their documentation.

Now you can move into the main folder and the storefront folder and run yarn dev separately to start up the backend and frontend both in development mode.

💡 To test out the integration that you’re going to build, you need some products in the storefront. Make sure to create some test ones yourself or insert some dummy data to the database by following the instructions here.

Connecting Redis

Now that you have a Medusa server up and running, you need to connect your Redis instance that you created. To do this, open the Medusa server folder (not the storefront) in your text editor, open the .env file and add the following line at the end of it. (Make sure to add your actual Redis URL at the end)

REDIS_URL=

Next, open the medusa-config.js file and inside the modules constant which is already defined, include the following object.

eventBus: {
  resolve: "@medusajs/event-bus-redis",
  options: {
    redisUrl: REDIS_URL,
  },
},

Right below, in the projectConfig object, uncomment the line with the redis_url to enable Redis.

Congratulations ! You have successfully connected Redis to your Medusa instance. Make sure to restart the Medusa server because a restart might be necessary for these changes to reflect.

Configuring Novu

Now that you have a Medusa instance up and running, you have to configure Novu.

Creating a Novu Account

To create a Novu account, head on over to Novu Signup page and either use GitHub login or email and password to create yourself a brand new Novu account.

Now, before you go ahead and create a Novu workflow, there are a few things that you should take note of.

First, go to the Integration Store from the left menu and see the integrations that are currently created. You can use the Novu test providers for now but in production, you need to make use of a third party provider like SendGrid.

Next, head on over to the Settings section from the left hand side menu and copy the API Key. You are going to need that just in a bit inside your code.

Creating a Novu Workflow for Email Notifications

Basically a workflow is how you send notifications in Novu, you simply create a workflow from the dashboard and trigger that workflow from the backend of your code.

To start creating a workflow, go to the workflow tab and click on Add a workflow , then choose a Blank workflow for now. On the top left of the page, you can name your workflow, I am going to name mine as “Medusa Novu Integration”. Naming the workflow will be important because you will be calling this workflow by its name.

In the middle of the page, you can see the area you will build your workflow on. Click the plus button below the Workflow trigger block and choose Email because you are going to be sending just Email notifications for now.

Next, click on the pencil icon to start editing your Email notification.

Start by setting the Sender name and Subject per your preference and move on to the Editor section. This Editor is where you will craft your email. Now you can style, add images and do all sorts of things to the email that you’re going to be sending in a bit, but for the sake of simplicity, copy and paste the below text in your editor.

Hey {{name}},

Thank you for placing your order with us.

Order ID - {{orderId}}
Amount - {{amount}}

Notice that there are some variables inside the double curly braces. These are variables that you can define from the backend when you’re sending an email.

Now that you’ve finished the work on Novu dashboard, click on the Update button on the top right.

Handling Store Events with Novu

There is an extensive array of events in Medusa that you can use to notify users. You can take a look at the whole list of events in the Medusa documentation.

But for the sake of this guide, you are going to be using the order.placed event mainly. As the name suggests, this event will be called when a user places an order from the frontend.

To listen to these events and send notifications, you can create a Notification Provider. You can find more information about that in their documentation.

For the Notification Provider to properly work, we need to set up two things inside of the Medusa codebase. Namely,

Service
Loader

Creating the Notification Provider Service

Start by creating a new TypeScript file inside the service directory inside the src directory. Make sure to use kebab-case when naming the file. As an example, I used novu-notifications.ts

Then copy and paste the following code inside that file, I will explain how each code block works in a bit.

import { AbstractNotificationService, OrderService } from "@medusajs/medusa";
import { Novu } from "@novu/node";

class NovuNotificationsService extends AbstractNotificationService {
  static identifier = "novu-notifications";

  protected orderService: OrderService;

  protected novu: Novu;

  constructor(container) {
    super(container);

    this.orderService = container.orderService;
    this.novu = new Novu(process.env.NOVU_API_KEY);
  }

  async sendNotification(
    event: string,
    data: any,
    attachmentGenerator: unknown
  ): Promise<{
    to: string;
    status: string;
    data: Record<string, unknown>;
  }> {
    if (event === "order.placed") {
      const order = await this.orderService.retrieve(data.id, {
        relations: ["customer", "shipping_address", "payments"],
      });

      const orderData = {
        orderId: order.id.split("_")[1],
        name: `${order.shipping_address.first_name} ${order.shipping_address.last_name}`,
        amount: (order.payments[0].amount / 100).toLocaleString("en-US", {
          style: "currency",
          currency: "USD",
        }),
      };

      await this.novu.trigger("medusa-store-notifications", {
        to: {
          subscriberId: order.email,
          email: order.email,
        },
        payload: orderData,
      });

      return {
        to: order.email,
        status: "done",
        data: orderData,
      };
    }
  }

  async resendNotification(
    notification: any,
    config: any,
    attachmentGenerator: unknown
  ): Promise<{
    to: string;
    status: string;
    data: Record<string, unknown>;
  }> {
    const to: string = config.to ? config.to : notification.to;

    await this.novu.trigger("medusa-store-notifications", {
      to: {
        subscriberId: to,
        email: to,
      },
      payload: notification.data,
    });

    return {
      to,
      status: "done",
      data: notification.data,
    };
  }
}

export default NovuNotificationsService;

Notice the imports. The AbstractNotificationService is the class that has extended the notification service class with. OrderService is used to access the order information like customer’s name and amount to include in the notification.
The Novu class is imported from @novu/node in order to make requests to the Novu API.

💡 Make sure to install the @novu/node\package by running npm i @node/novu\ inside the Medusa server
Next, you have the class named NovuNotificationService in this case and it requires a property named identifier. This will be used later inside the loader to call this specific notification service.
There are two variables defined for the Medusa services and the Novu and all of those two variables are initialized inside the constructor.

💡 Make sure to include the Novu API key you copied earlier inside the Novu constructor like this or via an environment variable. this.novu = new Novu("MY\_NOVU\_API\_KEY");\

Next, there are the two most important functions, sendNotification and resendNotification. The first function will be called when any of the events we have defined are triggered and the resend function is called when a resend notification is triggered from the admin panel.

Inside the sendNotification function,

The event is first checked, in this case, it only proceeds further if the event is order.placed which means a new order is placed.

Then all the details are accessed from the database with the call to orderService like this.

const order = await this.orderService.retrieve(data.id, {
  relations: ["customer", "shipping_address", "payments"],
});

Then you can see the data from the database call is organized in to a new object that matches what Novu requires. Notice that the keys here are the same as what you defined inside the Novu dashboard.

const orderData = {
  orderId: order.id.split("_")[1],
  name: `${order.shipping_address.first_name} ${order.shipping_address.last_name}`,
  amount: (order.payments[0].amount / 100).toLocaleString("en-US", {
    style: "currency",
    currency: "USD",
  }),
};

Finally, the Novu workflow you initially created is called with the necessary details to trigger an email notification like this. Notice that the email is passed into subscriberIdand email fields.

I was having a problem here regarding sending emails to users without subscribing them to an email list. I was able to get immediate support in Novu’s Discord server. I highly recommend you to leave a message on the Discord server if you need some immediate support.
```
await this.novu.trigger("medusa-store-notifications", {
  to: {
    subscriberId: order.email,
    email: order.email,
  },
  payload: orderData,
});
```

Inside the resendNotification function,

The previously sent notification details are passed into the function. So you can just take them and resend the notification as shown in the code.

That’s basically everything about the Notification Provider. The next important part is the loader function that will help this service class to be loaded in the Medusa environment.

Creating the Notification Provider Loader

Start by creating a new file named notifications.ts inside the src/loaders folder inside Medusa server with the following content.

import { MedusaContainer, NotificationService } from "@medusajs/medusa";

export default async (container: MedusaContainer): Promise<void> => {
  const notificationService = container.resolve<NotificationService>(
    "notificationService"
  );

  notificationService.subscribe("order.placed", "novu-notifications");
};

Notice in the last line, the service called novu-notifications is subscribed to the order.placed event. The service name here is the one that you defined as the identifier in the service file. Make sure that both the names across the files are matching.

Handling More Events

If you want to handle more events all you have to do is add another subscribe statement in the loader file like this.

notificationService.subscribe("order.refund_created", "novu-notifications");

In this case, this is being called when a refund is triggered.

And then send the notification with the related parameters from the service file. As it is mentioned earlier you can find all the events with their related data payloads are mentioned in the Medusa documentation.

That’s basically it. Now you should be ready to test this thing out!

Testing Notifications

To test notifications, go to the Medusa storefront, which is usually hosted on localhost:8000, choose a product, add it to the cart and place an order with some dummy details.

You can choose from a set of example products if you chose to seed dummy products in an earlier step.

If you have followed all the instructions and everything went well, you should now receive an email that looks something like this.

Conclusion

If you followed this tutorial, you should have a clear understanding of how to build an eCommerce store and even send a confirmation of purchase to the buyer!

Novu and Medusa have very responsive and helpful communities on Discord, so if you need help - just head there!

Thank you for reading so far! If you’ve found it helpful or would like me to cover something else, let me know down in the comments.

Implementing Authentication with Passkeys using Authsignal and Next.JS

Osada Vidath — Thu, 05 Oct 2023 17:18:55 +0000

Implementing Authentication with Passkeys using Authsignal and Next.JS

There are numerous ways to authenticate users, ranging from the basic username and password to advanced methods like JWT authentication, magic link, OTP, TOTP, security keys, and many more.

Passkeys have become the latest authentication trend. This new and convenient method eliminates the use of passwords or email codes for logging in. Passkeys allow users to access applications through their device's screen lock, such as fingerprint or face ID. Unlike passwords, passkeys are highly secure and protected from phishing attacks. They are also more secure than SMS OTPs, which can make users vulnerable to sim swapping.

Throughout this tutorial, you’re going to be learning about how you can implement passkeys authentication in your own app, with Authsignal which is an authentication as a service product which enables you to implement multi-factor passwordless authentication in the easiest ways possible.

Prerequisites

Having a basic knowledge of JavaScript and React is recommended to follow this tutorial more easily.

Configure Authsignal

Before proceeding with the tutorial, you need to create an Authsignal project. For this, you can go to authsignal.com and click on Create Free Account. Then you can go through their simple procedure and get your organization configured.

In the last step, you will create your first tenant - a project inside your Authsignal organization. Choose any name for your tenant and select the data storage region.

Configure Authenticators

Now that you have your Authsignal account configured you need to configure the authenticators that you’re going to be using for your project. We are going to be using email magic links and passkeys as the authenticators in this project. To configure those, click on the configure button you can see on the dashboard page.

and then you would see all the authenticators that you can use.

First, let’s configure the email magic link. To do that, click on the Set up Email Magic Link button and select Authsignal as the email provider. Now you have successfully configured email magic link as an authenticator.

Configuring passkeys has a pretty similar process, click on the Set up Passkey button. Since we’re just testing on localhost for the time being, make sure to set the Relying Party ID as localhost. (Make sure to change this when you’re moving your application to production)

Now you have successfully configured both the passkey and email magic link as authenticators.

API Keys

To connect Authsignal to your Next.JS application you would need the API key and some more information. You can obtain this information by clicking on the API Keys section in the left sidebar.

Take note of these because you’re going to need them in future steps.

Configuring the Next.JS Project

Now that we have completed the Authsignal setup, we can now proceed with the coding phase. We will be utilizing the Next.JS framework for our application development. Although React is an option, it requires a separate backend setup, making Next.JS a more practical choice.

Installing Next.JS

First, bootstrap a brand new Next.JS project by opening your CLI and running the following command.

npx create-next-app@latest

Then during the installation, you will see some prompts. I am going to use typescript and tailwind for this project but I am not going to use the Next.JS app router to keep this guide simple, also make sure to opt-in to creating a src folder to make following this tutorial easier.

Installing Required Dependencies

Now that you have the Next.JS project configured, let’s install the required dependencies. To do this cd into the folder that your project is in and run the following the command

npm i @authsignal/browser @authsignal/node axios cookie jwt-decode uuid && npm i -D @types/cookie @types/uuid

Two authsignal packages will be used to make communication with Authsignal servers easier, axios will be used to make HTTP requests to the backend from the frontend, uuid package will be used to generate a random identifier for new users, jwt-decode and cookie packages will be used to manage the user’s session inside the app.

Set up Magic Link Authentication with Authsignal

Before setting up authentication, you need to feed your API keys and other information into the project. In order to do this, create a .env.local file in the root of your project and add the following.

AUTHSIGNAL_SECRET=
NEXT_PUBLIC_AUTHSIGNAL_URL=
NEXT_PUBLIC_AUTHSIGNAL_TENANT_ID=
NEXT_PUBLIC_APP_URL=http://localhost:3000

You need to fill in this information with the details you obtain from your Authsignal dashboard and for the NEXT_PUBLIC_APP_URL you have to include the URL that your app is running on, so if you deploy your app, you need to replace this with the deployed URL.

If you're unfamiliar with email magic links, they're a method of authentication that involves entering your email address and receiving a link in your inbox. Once you click on that link, you'll be automatically logged in to the app.

Initializing Authsignal

To communicate with the Authsignal servers, you need to initialize two Authsignal clients. one for the front end and the other for the back end.

We’re going to make use of a custom react hook to initialize the front-end client. To do this, create a new file called useAuthsignalClient.ts inside the hooks folder inside the src folder and then paste the following code.

import { Authsignal } from "@authsignal/browser";
import { useEffect, useState } from "react";

const useAuthsignalClient = () => {
  const [client, setClient] = useState<Authsignal | null>(null);

  useEffect(() => {
    const authsignalClient = new Authsignal({
      tenantId: process.env.NEXT_PUBLIC_AUTHSIGNAL_TENANT_ID!,
      baseUrl: process.env.NEXT_PUBLIC_AUTHSIGNAL_API_BASE_URL!,
    });

    setClient(authsignalClient);
  }, []);

  return client;
};

export default useAuthsignalClient;

Here, we’re basically initializing a new object from the Authsignal class passing the tenantId and baserUrl to the constructor and we’re returning that from the hook so that we can use our authsignalClient without repeating this code snippet all over again.

Now to create our back-end client, create a file called authsignal.ts inside the lib folder and paste the following code snippet.

import { Authsignal } from "@authsignal/node";

const secret = process.env.AUTHSIGNAL_SECRET;

if (!secret) {
  throw new Error("AUTHSIGNAL_SECRET is undefined");
}

const apiBaseUrl = process.env.NEXT_PUBLIC_AUTHSIGNAL_API_BASE_URL;
const redirectUrl = `${process.env.NEXT_PUBLIC_APP_URL}/api/callback`;

export const authsignal = new Authsignal({ secret, apiBaseUrl, redirectUrl });

Here also we’re simply initializing an Authsignal object with the secret, apiBaseUrl and redirectUrl. Notice that the redirectUrl points to a backend function called callback, we will create that callback function in a moment.

Sign Up Backend Function

Authsignal SDK is designed in a way so that before doing anything in the front end, you first need to track that action through the backend. You can read more about this in the Authsignal’s documentation.

To do this, first, you have to set up an API route. In order to set up an API route, create a new file named email.ts inside the pages/api directory.

Then inside that email.ts file, paste this code.

import { authsignal } from "@/lib/authsignal";
import { NextApiHandler } from "next";
import { v4 } from "uuid";

const handler: NextApiHandler = async (req, res) => {
  const { url } = await authsignal.track({
    action: "signUp",
    userId: v4(),
  });

  res.status(200).json({
    url,
  });
};

export default handler;

Let’s go through the above code now,

First, we import the authsignal object that we exported earlier from the lib folder.
Then we’re going to track an action named signUp passing a random uuid that we can obtain with the u4 function in the uuid library as the userId
Finally, we’re sending the URL we get back from the Authsignal servers to the front end.

Homepage Frontend

Now we have the backend ready, let’s move on to the front end and hook our API route with a UI.

In the pages folder, you will see a file named index.tsx, which is where you write your front-end logic in Next.JS. Open that file and remove all the content in that file (Also open the styles/globals.css file and remove everything after the 3rd line to get similar styles)

First, let’s code a simple interface that looks something like this.

Paste the following code in the index.tsx file. This should get a basic interface like the above screenshot up and running.

const HomePage = () => {
  return (
    <div className="p-5 font-inter flex flex-col justify-center items-center">
      <h2 className="text-center text-3xl font-bold">
        Next JS + AuthSignal Passkeys Demo
      </h2>

      <div className="border rounded-lg flex flex-col mt-16 w-fit p-16 min-w-[750px]">
        <button className="border px-6 py-3 mt-2">
          Sign Up / Sign In
        </button>

        <p className="text-center my-5">or</p>

        <button>Sign in with an existing passkey</button>
      </div>
    </div>
  );
};

export default HomePage;

To make everything work, we need to import some libraries. Add these imports at the top of your file.

import { useEffect, useState } from "react";
import axios from "axios";
import { useRouter } from "next/router";
import useAuthsignalClient from "@/hooks/useAuthsignalClient";

Then inside the HomePage function, we’re first going to initialize all of these hooks. Add the following lines right at the beginning of the HomePage function.

const router = useRouter();
const authSignal = useAuthsignalClient();

Here we’re initializing the Next.JS router, this will be later used in order to redirect the user to the dashboard page after a successful login and then we initialize the hook that we made earlier to communicate with Authsignal from the frontend.

Now let’s create the signUp function to allow users to sign up for our application. To do this include the following snippet of code below where you initialized the hooks.

const signUp = async () => {
  const { data } = await axios.get("/api/email");
  window.location.href = data.url;
};

Here what we basically do is redirect the user to the Authsignal hosted sign-up page in order to complete the signup process.

Before we can test this out, we have to take care of several other things.

Callback Function

First of all, we need to take care of the callback function. This is where the user comes after they get authenticated from authsignal. We have already specified our redirect URL as /api/callback. Create a new file, name it callback inside the api folder, and paste the following code.

import { serialize } from "cookie";
import jwtDecode from "jwt-decode";
import { NextApiHandler } from "next";
import { authsignal } from "../../lib/authsignal";

const handler: NextApiHandler = async (req, res) => {
  const token = req.query.token as string;

  const decodedToken = jwtDecode<any>(token);

  const { state } = await authsignal.validateChallenge({ token });

  if (state === "CHALLENGE_SUCCEEDED") {
    const cookie = serialize("auth-session", token, {
      expires: new Date(decodedToken.exp * 1000),
      secure: process.env.NODE_ENV === "production",
      path: "/",
    });

    res.setHeader("Set-Cookie", cookie);
  }

  res.redirect("/dashboard");
};

export default handler;

You can find this code snippet in the example repository of Authsignal. What this basically does is take the returning auth token from authsignal and validate if that token is properly authenticated and if that token is properly authenticated, set a cookie named auth-session with that auth token and redirect the user to /dashboard page.

Authsignal Rules

Now since we have configured both the email and passkey providers inside of Authsignal, when you click on the sign up button, both the providers will be displayed but we don’t want that. We specifically want only the email provider to be displayed.

To do this, go to your Authsignal dashboard, choose the right project if you haven’t already, and then click on the actions menu from the top bar. Click on the new action button and create a new action with the name signUp.

Then go to the **rules** menu in the sidebar and click on create rule. Then you can give any name to the rule, choose challenge from the outcome menu, untick passkey and then save the rule.

Now you should be good to go ahead and test it. Click on the Sign-Up button and after following the on-screen instructions of entering the email and clicking on the link that you receive to the email, you should be redirected to /dashboard. Because we haven’t yet created a dashboard page, you will be redirected to a 404 page if everything goes well.

Dashboard Page

Now that we successfully get redirected to the dashboard page, let’s code a simple UI to display our email and a logout button that looks something like this

First, create a dashboard.tsx page inside the pages folder and paste the following code, then let’s go over the code line by line.

import { GetServerSideProps } from "next";
import { useRouter } from "next/router";
import { authsignal } from "@/lib/authsignal";
import jwtDecode from "jwt-decode";
import { VerificationMethod } from "@authsignal/node";
import useAuthsignalClient from "@/hooks/useAuthsignalClient";

export const getServerSideProps: GetServerSideProps = async (context) => {
  const token = context.req.cookies["auth-session"];

  if (!token) {
    return {
      redirect: {
        destination: "/",
        permanent: false,
      },
    };
  }

  const decodedToken = jwtDecode<any>(token);
  const userId = decodedToken.sub;

  if (!userId) {
    return {
      redirect: {
        destination: "/",
        permanent: false,
      },
    };
  }

  const user = await authsignal.getUser({ userId });

  return {
    props: {
      token,
      email: user.email,
      hasEnrolledPasskey: user.enrolledVerificationMethods?.includes(
        "PASSKEY" as VerificationMethod
      )!!,
    },
  };
};

const Dashboard = ({
  email,
  hasEnrolledPasskey,
  token,
}: {
  email: string;
  hasEnrolledPasskey: boolean;
  token: string;
}) => {
  const router = useRouter();

  const logOut = () => {
    document.cookie = `auth-session=; path=/; expires=Thu, 01 Jan 1970 00:00:01 GMT`;
    router.push("/");
  };

  const authSignal = useAuthsignalClient();

  return (
    <div className="p-5 font-inter flex flex-col justify-center items-center">
      <h2 className="text-center text-3xl font-bold">
        Next JS + AuthSignal Passkeys Demo
      </h2>

      <div className="border rounded-lg flex flex-col mt-16 w-fit p-16 text-center">
        <h3>You are logged in</h3>
        <p className="mt-2">Your email is {email}</p>

        {!hasEnrolledPasskey && (
          <span
            className="text-blue-600 cursor-pointer mt-5"
          >
            Save the passkey
          </span>
        )}

        <button className="border px-6 py-3 mt-10" onClick={logOut}>
          Sign Out
        </button>
      </div>
    </div>
  );
};

export default Dashboard;

We first have a getServerSideProps function on the top of the file. This function runs on the server before the page is rendered to the client. You can read more about this in the Next.JS documentation.

Inside the getServerSideProps function,

First, we read the cookie that we set before from the callback function and take it to the constant token.
If there is no token, we simply redirect the user to the home page.
If there is a token, we decode the token and take the userId from it.
If there is no userId which means the token is invalid, we redirect the user to the home page.
If there is a userId we pass that to the getUser function in authsignal and get back the user information.
Then we pass some of that information back to the client ( notice the hasEntrolledPasskey value, if this is true that means the user has already configured passkeys and if that is false that means the user has not configured passkeys. You will see how this is useful in the future parts of the tutorial)

Then inside the page, we simply render the information we got from the server side including a function called logOut that would clear the cookie and redirect the user back to the home page.

Also notice that if the user hasn’t enrolled passkeys, we render a text called Save the passkey. We will implement the functionality of this in the next section of the tutorial.

Set up Passkeys Authentication with Authsignal

If you followed until now, you should have correctly configured magic links as an authentication provider. Now let’s shift our focus to implementing passkeys.

First of all, you need to create a new API route. Create a new file, name it passkey.ts inside the api folder, and paste the following code.

import { authsignal } from "@/lib/authsignal";
import { NextApiHandler } from "next";

const handler: NextApiHandler = async (req, res) => {
  const { token } = await authsignal.track({
    action: "passkey",
    userId: "",
  });

  res.status(200).json({
    token,
  });
};

export default handler;

Nothing really new here, we just track a new action called passkey and send the token we get back to the front end.

Sign up for the passkey

Now, move on to the dashboard.tsx and inside the Dashboard function, create a new function as follows.

const passkeySignUp = async () => {
  try {
    await authSignal?.passkey.signUp({
      token,
      userName: email,
    });
    location.reload();
  } catch (error) {
    console.log(error);
  }
};

What this does is sign up that user with a passkey and reload the page if it is successful, or if it was unsuccessful, we just console.log the error.

In the markup, under the onClick handler of **************Save the passkey************** element, call this function like this.

{!hasEnrolledPasskey && (
  <span
    className="text-blue-600 cursor-pointer mt-5"
    onClick={passkeySignUp}
  >
    Save the passkey
  </span>
)}

Now, if you go to the /dashboard page and click on the **************Save the passkey************** button, your browser will prompt confirm your screen lock and the passkey will be saved. When the page refreshes, the **************Save the passkey************** should disappear.

Sign in with the passkey

To implement the login side of passkeys, go to index.tsx file, make sure axios is imported and add a new function like follows.

const passkeyLogin = async () => {
  const {
    data: { token },
  } = await axios.post("/api/passkey");

  const result = await authSignal?.passkey.signIn({
    token,
  });

  if (result) {
    window.location.href = `/api/callback?token=${result}`;
    router.push("/dashboard");
  }
};

Inside this function, we first get the token from the API function we created before and call the passkey sign-in function with that token.

Then if it returns a new token, we pass that token to our callback function to complete the login.

Now if you go to the homepage and click on the Sign in with an existing passkey button, you should be able to log in with the passkey you previously saved.

💡 This article goes over implementing passkeys and using Authsignal in a very basic manner. To implement passkeys in a real-world project. You would need a database to keep track of the user details.

Importance of Passkeys and Why Authsignal

As Google has explained here, passkeys are a very novel method of authentication and a very big step towards the passwordless future.

But it would be a very daunting task to implement passkeys on your own. This is where authentication as a service services comes in clutch. As we discussed throughout this article, you can set up passkeys to your own application in a few lines of code using Authsignal.

If you followed right until the end, now you know how to use Authsignal and more specifically how to implement passkeys without going through much trouble.

If you have any problems or if you want to take a look at the final code, you can check the GitHub repository with the completed code.

To learn more about Authsignal, visit the Authsignal documentation

How to Easily Set Up Advanced Analytics for Your Ecommerce Storefront

Osada Vidath — Wed, 12 Oct 2022 11:28:39 +0000

Medusa is hosting a hackathon during Hacktoberfest 2022. You can check it out and build something using Medusa to win awesome prizes. One example of a project for the Hackathon is integrating a third-party service like Matomo with Medusa, as shown in this article.

Aside from Medusa’s advanced ecommerce features, Medusa’s composable architecture and plugins system gives both developers and merchants the flexibility in choosing the services to integrate into their ecommerce store. One service that you can integrate for Analytics purposes is Matomo.

Matomo is an analytics platform just like Google Analytics but with some extra perks. Matomo can be self-hosted as well as used within their own SaaS version of the product which they call Matomo Cloud.

By using Matomo and integrating it with Medusa, you can track analytics related to user demographic, ecommerce events, and custom events that you can define. For example, how many times an item has been added to a cart.

In this tutorial, you will learn how you can integrate the Medusa storefront with Matomo Analytics to see basic stats like visit count, user behaviour, etc. You will also learn how you can work with Matomo event tracking.

You can obtain the source code for this tutorial on the GitHub repository.

Prerequisites

To use Medusa, you need to have Node.js installed on your local computer. If you don’t have it already, you can download it from the official Node.js website.

Configure Medusa

In this section, you will learn how to install and configure the three core parts of Medusa locally and prepare the Medusa storefront to be integrated with Matomo.

Install Medusa Server

Medusa server is the most important part of Medusa. It manages everything, including handling products, orders, payments, etc.

To use the Medusa server, you first need to install Medusa CLI by running the following command in your terminal:

npm install -g @medusajs/medusa-cli

Then, run the following command to create a new Medusa project via the CLI tool:

medusa new medusa-matomo --seed

Now, the CLI tool will download all the files and bootstrap a new Medusa instance. —seed flag will populate the database with dummy data.

When the project is successfully created, go into the directory it was created and run medusa develop:

cd medusa-matomo
medusa develop

If the server successfully started, you should see Server is ready on port: 9000 or something similar to that in the terminal output.

Configure Medusa Admin

Now that you have the Medusa server in place, you will also need an admin dashboard to do stuff like adding products, fulfilling orders, and much more. Fortunately, Medusa has also provided us with a Medusa admin panel that you could use for this purpose.

To get that up and running, first clone the admin panel from the GitHub repository:

git clone https://github.com/medusajs/admin medusa-admin

Once it is successfully cloned, change to the new directory and install all dependencies:

cd medusa-admin
npm install

Then, you can run the following command to start the admin panel:

npm run start

Once that has started, you can visit localhost:7000 and should see a login page.

Since you used --seed when creating the server at this point you should already have a user created. Enter admin@medusa-test.com as the email and supersecret as the password and login to the admin panel.

Configure Medusa Storefront with the Next.js Starter

Now that you have every backend component ready, you need to take care of the storefront. You can build a whole storefront yourself but for this tutorial, you’ll use the official Next.js Starter provided by Medusa.

To install the storefront, you can go to your preferred directory and run:

npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa medusa-matomo-front

This will create a new Next JS project with the Medusa Next JS starter code.

Change to the newly created directory and rename the .env.template file:

cd medusa-matomo-front
mv .env.template .env.local

To run your Medusa storefront, first make sure that the server is running, then run the following command:

npm run dev

This runs your storefront on localhost:8000. If you open it in your browser, you should see the storefront with some dummy products.

Configure Matomo

Now that you are done setting up all the Medusa stuff, you can move on to the Matomo side of things.

Create a Matomo Account

There are two ways to use Matomo: hosting it on your own or using their hosted service (Matomo Cloud). For this tutorial, you’ll use the free trial.

To get started with Matomo, you can go to the website and start by registering for their Matomo cloud 21-day trial. During the registration process, it asks for a website address, you can give your personal website or a dummy website address.

Once you have registered on their website, you will receive an email with a password to access your account.

Obtain Matomo Tracking Code

Login to your Matomo account following the instructions in the email you received and you should see something similar to this.

Now, you can click on the All Websites button in the top-right corner. Click on Add a new website and add your website. In the window that opens, choose Website.

In this case, I am going to name my website Medusa Matomo Demo and add localhost:8000 as one of the URLs.

Once you’re done, scroll down and click the Save button.

Now, on the next page, you can click on View Tracking Code and copy the whole code that is shown there without the opening and closing script tag.

Integrate Medusa Next JS Storefront with Matomo Analytics

Open the src/pages/_app.tsx file and import the Script component from the next/script package at the top of the file like this:

import Script from "next/script"

After importing the script module, include the snippet below inside the Hydrate component. Make sure to replace YOUR_MATOMO_TRACKING_CODE_HERE with the code you copied earlier in the above step:

<Script id="matomo_analytics">
    {`YOUR_MATOMO_TRACKING_CODE_HERE`}
</Script>

Once done, your app.tsx file should look similar to this. (Again, make sure to change the analytics code):

import { MEDUSA_BACKEND_URL, queryClient } from "@lib/config"
import { AccountProvider } from "@lib/context/account-context"
import { CartDropdownProvider } from "@lib/context/cart-dropdown-context"
import { MobileMenuProvider } from "@lib/context/mobile-menu-context"
import { StoreProvider } from "@lib/context/store-context"
import { CartProvider, MedusaProvider } from "medusa-react"
import { Hydrate } from "react-query"
import "styles/globals.css"
import { AppPropsWithLayout } from "types/global"
import Script from "next/script"

function App({ Component, pageProps }: AppPropsWithLayout) {
  const getLayout = Component.getLayout ?? ((page) => page)

  return (
    <MedusaProvider
      baseUrl={MEDUSA_BACKEND_URL}
      queryClientProviderProps={{
        client: queryClient,
      }}
    >
      <Hydrate state={pageProps.dehydratedState}>
        <Script id="matomo_analytics">
          {`
              var _paq = window._paq = window._paq || [];
  /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="https://xxx.matomo.cloud/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', '2']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.src='//cdn.matomo.cloud/xxx.matomo.cloud/matomo.js'; s.parentNode.insertBefore(g,s);
  })();
            `}
        </Script>
        <CartDropdownProvider>
          <MobileMenuProvider>
            <CartProvider>
              <StoreProvider>
                <AccountProvider>
                  {getLayout(<Component {...pageProps} />)}
                </AccountProvider>
              </StoreProvider>
            </CartProvider>
          </MobileMenuProvider>
        </CartDropdownProvider>
      </Hydrate>
    </MedusaProvider>
  )
}

export default App

Test Analytics

To test the integration, all you have to do is visit your website. You will see your visit on your Matomo dashboard. If you have multiple websites, make sure to switch between them using the select field next to the search field.

Matomo Event Tracking

At this point, you know how to set up basic analytics with Matomo. However, analytics is not always about visitor count and their country; you can also track user activity. For example, how many times users have clicked on the add to cart button or how many times users have scrolled to the end of the page.

You can do these very easily with Matomo event tracking.

Track the “Add to Cart” Event with Matomo

To do this, we’re going to use a package called matomo-tracker-react. You can install this by running the following command inside the Medusa storefront directory:

npm i @datapunt/matomo-tracker-react

If the command gives you an error, make sure to stop the Next.js server and try again.

Now, you have to make some modifications in _app.tsx file. First, you have to add the following imports at the top of the file:

import { MatomoProvider, createInstance } from "@datapunt/matomo-tracker-react"

Then just above your App function, you have to initialize a new instance of the library:

const instance = createInstance({
  urlBase: "https://osadathecoder.matomo.cloud/",
  siteId: 2,
})

If you’re wondering where the values of urlBase and siteId are coming from, they’re coming from the Matomo tracking code you previously got:

var _paq = window._paq = window._paq || [];
  /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    ***var u="https://osadathecoder.matomo.cloud/";***
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    ***_paq.push(['setSiteId', '2']);***
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.src='//cdn.matomo.cloud/osadathecoder.matomo.cloud/matomo.js'; s.parentNode.insertBefore(g,s);
  })();

See the parts that are italicized in the above tracking code. That’s where those values are coming from. Make sure to replace the values of urlBase and siteId with the values from your tracking code.

Finally, you have to wrap the whole app with a MatomoProvider passing it to the instance you created in the value prop:

function App({ Component, pageProps }: AppPropsWithLayout) {
  //...

  return (
    <MatomoProvider value={instance}>
      <MedusaProvider
        baseUrl={MEDUSA_BACKEND_URL}
        queryClientProviderProps={{
          client: queryClient,
        }}
      >
        <Hydrate state={pageProps.dehydratedState}>
          //...
        </Hydrate>
      </MedusaProvider>
    </MatomoProvider>
  )
}

export default App

Then to achieve your ultimate goal which was tracking the add-to-cart event, you need to find the place where the add-to-cart button is in the code. In the Next.js storefront you can find it in src/modules/products/components/product-actions/index.tsx.

Start off by adding the following import at the top of src/modules/products/components/product-actions/index.tsx:

import { useMatomo } from "@datapunt/matomo-tracker-react"

Inside the ProductAction component, initialize the useMatomo hook:

const { trackEvent } = useMatomo()

Finally, replace the button at the end of the returned JSX with the following:

<Button
  onClick={() => {
    addToCart();
    trackEvent({ category: "product", action: "add-to-cart" });
  }}
>
  {!inStock ? "Out of stock" : "Add to cart"}
</Button>

Previously, the button only added that specific item to the cart, but now it also tracks the add-to-cart event under the category of product using Matomo.

Test the Event

Start your Next.js storefront and make sure the Medusa server is also running.

Then, open the storefront and add a product to the cart.

Next, check the Matomo dashboard. Under the actions of the current session, you should see an event being recorded. If you hover over the icon, you can see the event name.

If you go to Visitors → Visits Log, you should see the event with the page where the event occurred.

Now, you can track any event that is happening on the webpage by following the above steps using Matomo.

Conclusion

Medusa’s headless architecture and plugin system allow developers to pick and choose which services to utilize in their ecommerce store.

One of the many services you can integrate into Medusa is Matomo. By combining Medusa and Matomo’s features, you can maximize your ecommerce store’s capabilities by tracking different types of events and understanding your customer’s behaviours.

Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.