DEV Community: Common Ninja

Common Ninja Platform News: Squarespace Integration | Payment Plans Metadata | Shopify Partners Integration

Daniel Sternlicht — Wed, 31 Aug 2022 07:20:47 +0000

We are very excited to share with you recent news and updates related to our developer platform.

Although August is mostly a quiet month, we worked hard to add amazing features to Common Ninja's Developer Platform including new e-commerce and payments APIs, a new e-commerce integration with Squarespace, and an interesting connection between Common Ninja and Shopify's partners API.

Just to remind you, Common Ninja is a developer platform for building and monetizing universal e-commerce apps. We provide a universal e-commerce API that allows developers to build apps once and launch them across multiple platforms. In addition, Common Ninja provides integrations with popular payment platforms - helping developers to monetize their apps very easily.

🎉 What’s New:

Squarespace integration
Payment plans metadata
Integration with Shopify Partners API
APIs
- Product images API
- Checkout URL API
- User subscriptions API

Squarespace integration

We're happy to announce our 9th e-commerce platform integration support, which will allow you to make your app accessible to Squarespace merchants and users.

In order to add the integration, you'll need to create a Squarespace app, and use the provided client ID and client secret. You can learn more about it here.

Payment plans metadata

Introducing the payment plan metadata editor — a new way to add custom metadata based on your app's needs. You can attach metadata to any plan or feature created in the Common Ninja's payments admin, and then consume it with the payment plans API.

Shopify Partners API integration

We're truly excited about this one.

This month we've added an option to connect your Common Ninja app to Shopify Partners’ API, allowing you to see subscriptions, payments, and the usage data of your universal e-commerce. Not only will this information be from Shopify merchants, but also from all other merchants from any other platform that your app is integrated with — all in one place!

Learn more about how to connect your Common Ninja app to Shopify here.

New APIs

We've added support for 3 new APIs:

Product images API: A new set of CRUD APIs for better management of the product images resource.
Checkout URL API: A simple endpoint for getting the checkout URL of a payment plan integrated with our payment integrations' solution.
User subscriptions: A new endpoint for fetching a list of user's subscriptions based on status or platform.

If you have any specific requests or ideas, we'll be more than happy to hear them 🙂

📚 Learn more

You can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

Fixing "frame-ancestors directive" Errors on Shopify Embedded Apps

Daniel Sternlicht — Mon, 22 Aug 2022 07:40:06 +0000

Building a Shopify app can be complex, and you might face many challenges during the process. From understanding the authentication flow to using the different APIs, and handling webhooks.

When you build a Shopify app, you can choose either if you want your app to be an embedded app or not.

Embeddable app - You can let merchants access and interact with your app within the Shopify admin or Shopify POS.
Non-embeddable apps- Merchants install your app and are then redirected outside of Shopify to your app's hosted page.

If you decided to build an embedded app for Shopify you’ll need to make sure that your app is secured and meets Shopify’s security policies and standards.

One of the most common content security policy Shopify requires you to handle is the frame-ancestors - which tells the browser to allow or disallow the resources getting embedded using iframe, frame, object, embed, and applet element.

I saw that many developers are facing issues with embedded apps and looking for solutions in different communities, so I decided to write about it.

Here are the top 4 frame-ancestors errors on Shopify embedded apps and how to fix them.

1. The 'content-security-policy' header should set frame-ancestors https://[shop].myshopify.com https://admin.shopify.com, where [shop] is the shop domain the app is embedded on.

When you submit an app to Shopify, it might be rejected even before it got to the review team. Shopify has a set of automations that run when you submit your app. If you got the above rejection, it means that you haven't set the Content-Security-Policy: frame-ancestors <source>; header.

In order to fix it you'll need to add the frame-ancestors header on the response of the frame's request:



// A middleware for setting up the header
router.use((req, res) => {
  const shop = req.query.shop;
  if (shop) {
    // Set the `frame-ancestors` header on the response
    res.setHeader(
      'Content-Security-Policy',
      `frame-ancestors https://${shop} https://admin.shopify.com;`
    );
  }
});

router.get('/app', (req, res) => {
  // Send a file, or redirect to your app's frame
  res.sendFile(path.join(__dirname, '../public', 'index.html'));
});

Please note: the frame-ancestors header must be different for each shop.

2. Refused to frame '{URL}' because it violates the following Content Security Policy directive: "child-src 'self' https://* shopify-pos://*". Note that 'frame-src' was not explicitly set, so 'child-src' is used as a fallback.

This error might be caused because you're trying to load a non-secured URL. Make sure that the App URL you're using is under the HTTPS protocol and not HTTP.

If you're running locally (localhost) you might want to use a tunnel service such as ngrok or localtunnel.

3. On Safari: [Error] Refused to load https://XXXX.myshopify.com/admin/auth/login because it does not appear in the frame-ancestors directive of the Content Security Policy.

Safari is a more strict browser than Chrome or Firefox, this error might appear if you're trying to redirect the user to a different URL after the initial app URL was loaded.

To fix this issue you'll need to make the redirect from the client instead of the server. Here's how:



function generateRedirectHtml(redirectUrl) {
  return `
  <!DOCTYPE html>
  <html>
    <head>
      <title>Redirecting, please wait...</title>
      <script>
        setTimeout(()=>{
          window.top.location="${redirectUrl}";
        }, 3000);
      </script>
    </head>
    <body>
        Redirecting...
    </body>
  </html>
  `;
}

router.use((req, res) => {
  const redirectUrl = 'YOUR_REDIRECT_URL';
  const userAgent = req.headers['user-agent']
    ? req.headers['user-agent'].toLowerCase()
    : '';

  // For Safari, use client redirect
  if (
    userAgent.includes('shopify') ||
    (userAgent.includes('safari') &&
      !userAgent.includes('chrome') &&
      !userAgent.includes('firefox'))
  ) {
    res.send(generateRedirectHtml(redirectUrl));
    return;
  }

  // For other browsers, use redirect header
  res.redirect(redirectUrl);
});

4. Refused to display '{URL}' in a frame because it set 'X-Frame-Options' to 'deny'.

This error might appear when you're trying to redirect a user to your app's checkout page, or on the first time your app loads.

The first thing you need to do is to make sure that the App URL is being configured correctly for the app.

Next, if you're trying to make the redirect from the server, try instead to make a request to the server to get the redirect URL, and make the actual redirect from the client. For example



async function getRedirectUrl() {
  const result = await (await fetch('/getRedirectUrl')).text();
  window.location.href = result;
}

<button onClick={getRedirectUrl}>Click Me</button>

I hope this post will help you not to spend more time on fixing frame-ancestors errors on Shopify. If not, or if you have any other errors that you've seen, please leave a comment and I'll update the blog post.

In addition, if you're not familiar with the Common Ninja Developer Platform, that might be a good time to mention that you can spend less time integrating with Shopify and handling these kinds of errors by using our platform 🙂

❓ What is Common Ninja?

Common Ninja is a platform that helps developers to build & monetize apps for e-commerce platforms very easily. With our single e-commerce API you can build your app once, and integrate it with multiple platforms like Shopify, BigCommerce, Wix, WooCommerce, and more. There's no need to rebuild the app and make it work on every platform individually.

In addition, Common Ninja offers a set of APIs and tools that help developers to boost up the development process, and provide payments and storage solutions.

📚 Learn more

If you're not familiar with Common Ninja or how to build your first app using our API, here's the previous article we wrote about it.

In addition, you can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

Common Ninja's Template for WooCommerce - Bring Your E-Commerce App to WooCommerce With Zero Effort

Daniel Sternlicht — Mon, 18 Jul 2022 11:13:00 +0000

Developing a WooCommerce plugin is not the greatest experience for developers.

If you decide that you want to bring your e-commerce app to WooCommerce, you'll need to download WordPress, learn PHP, and hack your way through WordPress' different APIs and hooks in order to build the plugin you want.

It’s safe to say that if you developed the original app for Shopify, BigCommerce, or Wix, you probably didn’t use PHP as your backend, or even plain HTML. In WordPress / WooCommerce you must use both, and the plugin development process will require you to upload your plugin's files to WordPress’ plugins directory, rather than load the app remotely from a URL.

At Common Ninja, we believe that developers should focus and spend their time on building the product side of their e-commerce app, and not on the integrations with the different e-commerce platforms.

The way we do that is by creating a set of tools for e-commerce app developers that allow them to reduce the time they spend on platform integrations by 90%, and to create one universal e-commerce app for all platforms.

This is why we're so happy to introduce to you Common Ninja's template for WooCommerce — a simple way to bring your Shopify app to WooCommerce.

Link to the template's repository:
https://github.com/CommonNinja/woocommerce-plugin-template

How to use

1) Download || clone the following repo.

git clone https://github.com/CommonNinja/woocommerce-plugin-template.git

2) Change the main folder's name (plugin-template) to your plugin's slug name.

The plugin's slug name must be unique, lower and kebab case. 3) In the plugin-template folder, rename the plugin-template.php file to the slug name you chose in the previous step. 4) Open the config.php file under the plugin-template folder and change the following details:
cn_app_id - Your public Common Ninja's app ID.
plugin_name - The name of the plugin as it will appear on WordPress's menu.
plugin_icon - The icon of the plugin as it will appear on WordPress's menu. (accepts url, base64 format, or relative path from the _inc folder as root). 5) In the plugin-template file, change the meta data of the plugin (the comments on top).
Note, the Text Domain setting must be your plugin's slug. 6) Edit and change the details on the readme.txt file under the plugin-template folder.

Please note, the actual folder that you'll use for pushing your code to WordPress's SVN repo is the main folder (the one that includes the plugin-template and assets folders).

Next steps

Once your plugin is ready, the next step will be to submit it to WordPress' plugin directory.

1) Create a .zip file from the main plugin-template folder.

2) Go to https://wordpress.org/plugins/developers/add/ and submit the zip file.

3) After WordPress' team reviews it, you'll get an email from plugins@wordpress.org. This email will contain two links. For example:

SVN URL: https://plugins.svn.wordpress.org/{PLUGIN_NAME}
Public URL: https://wordpress.org/plugins/{PLUGIN_NAME}

4) Run the following command to download your new repository code:

svn co https://plugins.svn.wordpress.org/{PLUGIN_NAME} {PLUGIN_NAME}

5) Copy the original code from the previous section to the trunk folder. Add the relevant assets to the assets folder (icon and banner).

Your project's file structure should look like that:

- assets
- tags
- trunk
 |__ _inc
 |__ commonninja
 |__ {PLUGIN_NAME}.php
 |__ config.php
 |__ readme.txt

6) Browse to the plugin's folder and add the new files to svn:

cd {PLUGIN_NAME}
svn add trunk/*
svn add assets/*

7) Commit and push changes to WordPress:

svn ci -m 'Adding first version of my plugin'

And that's it! Your app will be ready to be used by WooCommerce users.

❓ What is Common Ninja?

Common Ninja is a platform that allows developers to build & monetize apps for e-commerce platforms very easily. With our single e-commerce API you can build your app once, and integrate it with multiple platforms like Shopify, BigCommerce, Wix, WooCommerce, and more. There's no need to rebuild the app and make it work on every platform individually.

In addition, Common Ninja offers a set of APIs and tools that help developers to boost up the development process, and provide payments and storage solutions.

📚 Learn more

If you're not familiar with Common Ninja or how to build your first app using our API, here's the previous article we wrote about it.

In addition, you can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

Common Ninja Platform News: New Dashboard | Store Details API | Summer Hackathon

Daniel Sternlicht — Mon, 11 Jul 2022 12:32:33 +0000

We are very excited to share with you recent news and updates related to our developer platform.

This month we announced our summer hackathon for e-commerce app developers, a couple of new commerce APIs, and a brand new dashboard where you can see statistics and important information about your app.

🎉 What’s New:

New dashboard (!)
APIs
- Store details API
- Orders' range filter
- Proxy API
Summer hackathon

New Dashboard (!)

The new dashboard was released this month and introduce some important information and useful statistics about your app.

The new dashboard gives you an overall snapshot of your app's performance, how many stores are using your app, and how many active subscriptions your app has. In addition it will show you information about your app's revenue and installations based on data from multiple platforms.

New APIs

We added support for 3 new APIs:

Store details API: An endpoint for getting the store's basic details such as name, url, currency, and country.
Orders' range filter: We've added support for fetching a list of store's orders with a time range filter.
Proxy API: An endpoint proxies requests to the relevant resource on a specific platform.

Summer Hackathon for E-Commerce App Developers

As announced earlier this month, our summer hackathon was officially launched last week with more than 180 developers who signed up to participate and develop e-commerce apps.

Learn more about the hackathon:
https://www.commoninja.com/hackathon-2022/

If you have any specific requests or ideas, we'll be more than happy to hear them 🙂

📚 Learn more

You can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

Common Ninja's Summer Hackathon: Build E-Commerce Apps, and Win Awesome Prizes!

Daniel Sternlicht — Mon, 04 Jul 2022 10:18:10 +0000

The e-commerce market is huge and presents numerous opportunities for developers and companies to bring their innovation and creativity forward and solve problems for merchants and their customers.

From tools that improve conversions, to smart automations that optimize sales, to useful apps that help bring more customers and more.

We're happy to announce a Common Ninja's virtual hackathon for e-commerce app developers 🎉

In the hackathon, you will build an e-commerce app using Common Ninja's universal API for commerce. You'll only need to focus on building the app’s functionality while the Common Ninja platform will take care of the integrations, authentication and monetization of your app.

Registration ends on July 7th, 2022. So hurry up!

Common Ninja Starter Kit - A Boilerplate Project For Building Universal E-Commerce Apps With NodeJS & React

Daniel Sternlicht — Thu, 30 Jun 2022 10:02:38 +0000

In one of the previous articles we wrote, we walked you through the process of building your first Shopify app with Common Ninja, NodeJS, and React.

The article was very detailed, and contained a lot of code examples, but we got some feedback from many developers that it would be helpful to get a boilerplate project that will save more time on bootstrapping a new project.

Well, your prayer was heard, and today we're happy to launch the official Common Ninja Starter Kit for NodeJS & ReactJS developers.

The project is available in the link below 👇🏻, and you can follow the main README.md file to see how it works:
https://github.com/CommonNinja/commonninja-node-react-starter-kit.

The starter kit will enable you to run a single command, after which you'll be able to start working on your universal e-commerce app. The app will be able to support multiple platforms, including Shopify, BigCommerce, WooCommerce, Wix, and more.

Prerequisite

In order to run the project you'll need the following:

Docker
Yarn
An account and an app on the Common Ninja Developer Platform

Once you have these, the next step would be to prepare your environment.

Getting Started

Clone the starter kit repository:

git clone https://github.com/CommonNinja/commonninja-node-react-starter-kit.git

Browse to the project's folder (cd commonninja-node-react-starter-kit) and run the following script:

./scripts/dev-setup.sh

In the packages/server folder, edit the .env file and set your Common Ninja app credentials:

# Common Ninja App
COMMONNINJA_APP_ID=XXXX-XXXX-XXXX-XXXX-XXXX
COMMONNINJA_APP_SECRET=cn_XXXX-XXXX-XXXX-XXXX-XXXX

Next, start the project by running:

docker compose up

Browse to the project locally at http://localhost:3000.

And that's it!

You can read more about the project's structure here.

What's next?

The next thing you should do, is to start adding integrations to e-commerce platforms, and connect your app to payment providers.

You may read more about it in Common Ninja's official documentation.

❓ What is Common Ninja?

In addition, Common Ninja offers a set of APIs and tools that help developers to boost up the development process, and provide payments and storage solutions.

📚 Learn more

If you're not familiar with Common Ninja or how to build your first app using our API, here's the previous article we wrote about it.

In addition, you can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

Common Ninja Platform News: Storage API | Payment Trials | Webhooks Management

Daniel Sternlicht — Tue, 14 Jun 2022 07:15:07 +0000

We are very excited to share with you recent news and updates related to our developer platform.

This month we announce the new Storage API, a full support in payment trials, and a brand new webhooks management tool.

Just to remind you, the Common Ninja Developer Platform allows you to build & monetize apps for e-commerce platforms very easily. With our universal e-commerce API you can build your app once, and integrate it with multiple platforms like Shopify, BigCommerce, Wix, WooCommerce, and more. There's no need to rebuild the app and make it work on every platform individually.

🎉 What’s New:

Storage API
Payment trials support
Webhooks management tool

Storage API

Earlier this month we announced the new Storage API and platform integrations - an easy way for adding storage capabilities to any e-commerce app.

The new API is simple and you can decide whether you want Common Ninja to manage your storage, or to integrate it with your own AWS S3 bucket.

We wrote a detailed article about the motivation behind it as well as how to start using it. See below:
https://dev.to/commonninja/announcing-common-ninja-storage-a-simple-api-for-adding-storage-capabilities-to-e-commerce-apps-2dii

Payment Trials

Last month we introduced the new payments capabilities that will allow you to seamlessly monetize your app by connecting it to popular payments platforms like Stripe, PayPal, Paddle, BlueSnap, and Shopify app payments solution.

With Payments you can create payment plans and set the amount and period you want to charge your users.

A new feature that we added is payment trials that enables you to set time so your users will be able to test your app for free before they start paying.

Webhooks Management Tool

One of the most difficult thing to track and debug when you're developing an app is webhook messages that being sent by 3rd party platform and being received by your server. This is why we developed the new Webhooks Management Tool. With the new tool you can:

Create multiple webhooks
Resend webhook messages
View messages' payload, request, status code, and error.

The new tool is available under the "Webhooks" menu item in the Common Ninja app's dashboard.

If you have any specific requests or ideas, we'll be more than happy to hear them 🙂

📚 Learn more

You can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

Announcing Common Ninja Storage - A Simple API For Adding Storage Capabilities to E-Commerce Apps

Daniel Sternlicht — Mon, 06 Jun 2022 12:18:19 +0000

We’ve recently built a new app for Shopify and other e-commerce platforms. The app allows merchants to add info labels to a product image. This is a very common use case, as merchants frequently create multiple variations of a product image to highlight some of the product's features.

One of the app’s features is the ability to create an image with the info labels editor we’ve built, and then to save it for future use. To make this possible, we needed to integrate with a storage solution such as AWS S3, Google Cloud Storage, Azure Blob Storage, etc.

For some reason, adding this capability and understanding what the best way to save files on a cloud storage was, as well as coding the feature end-to-end in both client and server sides — wasn't an easy task at all (although this is something I've handled dozens of times).

Our stack includes React, Node and AWS S3. Having said that, here are some of the problems we encountered:

How to send an image from a ReactJS app to a server?
How to accept an image file in NodeJS?
How to save an image to AWS S3?
How to get the uploaded image URL?
How to create and manage folders for each user?

These seem like trivial questions, but answering each one of them and understanding how they all play together is something that can take a long time.

I believe that the main issue here is that there are multiple ways to upload images from client to server — base64, urls, form-data, blobs. So many terms when the only thing you want, as the app's developer, is to allow your users to upload images and files.

❓ What is Common Ninja?

In addition, Common Ninja offers a set of APIs and tools that help developers to boost up the development process, and provide payments and storage solutions.

📣 Announcing Common Ninja Storage

Common Ninja's Storage solution is a new and easy way for adding storage capabilities to any e-commerce app.

Our API is simple and you can decide whether you want Common Ninja to manage your storage, or to integrate it with your own AWS S3 bucket.

You can read more about the API in our docs.

💻 Code Example

We'll publish a much more technical article soon, but meanwhile, just to taste how easy it is, here's a quick code example from our Info Labels app (developed with React & NodeJS).

import React, { useState } from 'react';

function FileUpload() {
    const [selectedFile, setSelectedFile] = useState<string | Blob>('');

    const changeHandler = (event: any) => {
        setSelectedFile(event.target.files[0]);
    };

    const uploadImage = async () => {
        try {
            const body = new FormData();
            body.append('file', selectedFile);
            const req = await fetch('/api/storage/files', {
                method: 'POST',
                body,
            });
            const {
                data: { url },
            } = await req.json();

            console.log('File url: ', url);
        } catch (e) {
            console.error('Could not upload image', e);
        }
    };

    return (
        <div>
            <input type="file" name="file" onChange={changeHandler} />
            <div>
                <button onClick={uploadImage}>Upload</button>
            </div>
        </div>
    );
}

Next, in our NodeJS server we use Common Ninja's API to upload the file and return its url:

import { Request, Response, Router } from 'express';
import CommonNinja from '@commonninja/node-sdk';

const router: any = Router();
const { COMMONNINJA_APP_ID, COMMONNINJA_APP_SECRET } = process.env;

function getCommonNinjaClient(req: Request) {
    if (!COMMONNINJA_APP_ID || !COMMONNINJA_APP_SECRET) {
        throw new Error('Missing Common Ninja app ID or secret key.');
    }

    return new CommonNinja({
        appId: COMMONNINJA_APP_ID,
        appSecret: COMMONNINJA_APP_SECRET,
        accessToken: req.query.token as string,
        env: CommonNinja.envs.production,
        logs: true,
    });
}

router.post('/api/storage/upload', async (req: Request, res: Response) => {
        const client = getCommonNinjaClient(req);
        const result = await client.storage.uploadFile(req.body.file);
        res.send(result.data);
});

And that's it! Zero effort and your users can upload images, videos, documents, and any other file you want your app to support.

📚 Learn more

If you're not familiar with Common Ninja or how to build your first app using our API, here's the previous article we wrote about it.

In addition, you can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

May 2022: What's New in Common Ninja Integrations

Daniel Sternlicht — Mon, 23 May 2022 12:27:25 +0000

❓ What is Common Ninja?

In addition, Common Ninja offers an easy way to monetize your app by creating payment plans, and connecting them to the most popular payments platforms such as PayPal, Stripe, Paddle, etc.

📣 What's new in Common Ninja integrations?

We're constantly working on improving the platform and adding support for more integrations, each of which can help solve issues in different areas of the e-commerce app development process.

E-Commerce

We started with e-commerce platform integrations and we currently support the following platforms:

The meaning of these integrations is that Common Ninja provides an API for authenticating, marking API calls for consuming resources (such as products, customers, orders, etc.), and handling webhooks - all from a single interface.

Payments

Earlier this month we announced our payment solutions. This solution is a game changer for developers as it simplifies the way you can monetize your app.

With a simple interface you can define the available features that your app has to offer, and then create plans for different tiers and users. For each plan you can set multiple prices (i.e monthly or annually), and then to access everything through an API and get the checkout URL for each plan.

And the best part is that you can connect multiple payment platforms (!).

The payment platforms we currently support are:

*Shopify has a payment solution for app developers.

You can learn more about how it works here.

🚀 What's next?

Our roadmap is full and we're working hard (and fast) to add more integrations that will solve different problems and accommodate different needs.

We plan to add support to more e-commerce and payment platforms, as well as storage and email marketing solutions - everything that is required for building the best e-commerce app for your customers, as fast as possible.

If you have any specific requests or ideas, we'll be more than happy to hear them 🙂

📚 Learn more

You can use the following resources to learn more and get help:

📜 Common Ninja Docs
💬 Discord Community

Kick-Off Your First Shopify App With React, NodeJS and Common Ninja

Daniel Sternlicht — Mon, 16 May 2022 12:23:50 +0000

Let's start at the end. There are tons of tutorials and resources out there on how to build apps for Shopify, so what's so special about this one?

Well, I'm glad you asked! 😉

If you had any previous experience with building Shopify apps, you probably wasted endless time on reading their documentation, trying to understand the authentication flow, connecting to webhooks, testing different ways to charge money for your app — basically - trying to connect everything together.

The thing is, once you’ve finished building your app (and presuming that you’ve survived the above process) it will only be available to Shopify merchants. But what about other e-commerce platforms like WooCommerce, Wix, BigCommerce, etc.? Your app is probably suitable for them as well. But in order to make it work on those platforms, you'll need to rewrite your app from scratch and, in some cases, you'll need to add more capabilities that aren’t supported by these platforms, like monetization and payments.

You can read more about The Problems With Building Apps for E-Commerce Platforms in a previous post we wrote.

At Common Ninja we solve these problems by providing developers with a single interface for E-Commerce and payments platforms, allowing you to focus solely on building the business logic of your app, rather than spending too much time on integrating it with multiple platforms.

In this article, I'll walk you through the process of building your first Shopify app with Common Ninja, NodeJS, and React. And the best part? Once your app is ready, you can use the same code to monetize it on other e-commerce platforms that we support! 🚀

Requirements

Before we start, there are a few things you need to set, so make sure you have the following:

A developer account on Common Ninja.
A partner account on Shopify.
An integration between Shopify and Common Ninja. See a tutorial here.

Technical requirements:

NodeJS
Yarn
Docker
VSCode (or any other code editor)

Installation

If you have all of the above installed you can start running the following code to create a comfortable environment and start working on your app with a simple integration to Common Ninja:

npx @commonninja/create-nindo-app project-name

You'll be asked to select a template. For the purpose of this quick start tutorial, choose the Server template.

The project will automatically install all of its dependencies.

Setup

Open the generate project in VSCode - or any other code editor you're using, and edit its .env file:

# Env
PORT=4000

# Common Ninja App
COMMONNINJA_APP_ID=
COMMONNINJA_APP_SECRET=

Set the COMMONNINJA_APP_ID and the COMMONNINJA_APP_SECRET based on your Common Ninja app (if you haven't created an app yet, now is the time):

Next, start the development server by running:

docker compose up

Make sure that the server is up and navigate to localhost:4000. You should see a Hey there! message.

Project Structure

This is a very simple and basic NodeJS project with Docker. It is already set up with TypeScript and an automatic watch on files for server restart. Under the src folder there are two files:

src
    app.ts
    routes.ts

app.ts

A very common NodeJS app entry file. Here we set up the initial Express server:

import 'dotenv/config';

import express from 'express';
import cookieParser from 'cookie-parser';
import bodyParser from 'body-parser';

import router from './routes';

const port = parseInt(process.env.PORT || '3000');
const app = express();

// Parse cookies
app.use(cookieParser());

// Parse application/x-www-form-urlencoded
app.use(bodyParser.urlencoded({ extended: false }));

// Parse application/json
app.use(
    bodyParser.json({
        limit: '50mb',
    })
);

app.use('/', router);

// Start server
app.listen(port, () => {
    console.log(`Running at http://localhost:${port}`);
});

module.exports = app;

Nothing special here.

routes.ts

This is an example of how to use Common Ninja's Node SDK library. Each one of the routes is initializing the CommonNinja class:

const { COMMONNINJA_APP_ID, COMMONNINJA_APP_SECRET } = process.env;

function getCommonNinjaClient(req: Request) {
    if (!COMMONNINJA_APP_ID || !COMMONNINJA_APP_SECRET) {
        throw new Error('Missing Common Ninja app ID or secret key.');
    }

    // Create a new Common Ninja instance
    return new CommonNinja({
        appId: COMMONNINJA_APP_ID,
        appSecret: COMMONNINJA_APP_SECRET,
        accessToken: req.query.token as string,
        env: CommonNinja.envs.production,
        logs: true,
    });
}

In the routes.ts file we define 3 routes, each one interacts with different parts of Common Ninja's API.

/connect

The /connect route is responsible for redirecting your user to an authentication flow with the platforms your app supports. So if you've added the Shopify and WooCommerce integrations to your Common Ninja app - by browsing to http://localhost:4000 you'll see these platforms' logos.

By clicking on one of them you'll be redirected to the platform's authentication page. Once the authentication flow is done, Common Ninja will redirect the user to the Redirect URL you defined in the relevant section of your app's dashboard.

The code that handles this route is using the SDK's getConnectUrl method:

// Authentication
router.get('/connect', async (req: Request, res: Response) => {
    // Get a new Common Ninja instance
    const client = getCommonNinjaClient(req);

    // Get authentication url for platform
    const url = client.auth.getConnectUrl();

    // Redirect to authentication url
    res.redirect(url);
});

/api

This route is in fact a proxy to Common Ninja's API. The SDK has a built-in proxy method that handles the incoming requests:

// API Proxy
router.all('/api*', async (req: Request, res: Response, next: NextFunction) => {
  // Get a new Common Ninja instance
  const client = getCommonNinjaClient(req);

  // Proxy api requests to Common Ninja API
  return client.apiProxyMiddleware(req, res, next, '/api');
});

The 4th parameter in the apiProxyMiddleware method is the route in your app that will be rewritten.

For example:
/api/ecommerce/products will be proxied to https://api.commonninja.com/integrations/api/v1/ecommerce/products.

Please note: You don't have to use the API that way, instead you can support selected APIs by using the different methods the SDK supports. For example:

router.get('/api/products', async (req, res, next) => {
    const client = getCommonNinjaClient(req);
    const data = await client.ecommerce.getProducts();
    res.send(data);
});

/webhooks

Lastly, the /webhooks route will accept webhook messages from Common Ninja's supported platforms. You may read more about Webhooks here.

Webhook messages should be validated, and our SDK will take care of that for you:

// Validate and handle Common Ninja's webhooks
router.post('/webhooks', async (req: Request, res: Response) => {
    try {
        const client = getCommonNinjaClient(req);

        // Validate webhook message source
        const validated = client.webhooks.validateWebhook(req);
        if (!validated) {
            throw new Error('Cannot validate signature.');
        }

        console.log('Webhook message', req.body);

        // Send a 200 OK response back to Common Ninja
        res.sendStatus(200);
    } catch (e) {
        console.error(`Cannot handle webhook message`, e);
        res.status(500).send((e as Error).message);
    }
});

In order to test the webhooks, you'll need to work with https protocol locally. The way we handle it is by using tunnels.
This project has another docker compose file for this purpose. Run:

docker compose -f docker-compose.https.yml up

And you'll get a secured URL that you can use to test the webhooks integration:

Once you have the URL, simply add a new webhook URL to your Common Ninja app:

Client

Now that we have the server ready, let's create a simple react app using React CRA:

npx create-react-app client-app

Open the generated project, look for the package.json file, and add a proxy property:

{
  ...
  "proxy": "http://localhost:4000",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  ...
}

React will proxy requests to the server we created.

Next, let's start the project with npm start.

Just for the sake of the simplicity, we'll see how easy it is to access Common Ninja APIs through the app, without adding a single line of code to the server.

Let's edit the App.jsx file.

import { useState, useEffect } from 'react';

import './App.css';

function App() {
  const searchParams = new URLSearchParams(window.location.search);
  const [token] = useState(searchParams.get('token'));
  const [products, setProducts] = useState([]);

  async function getProducts() {
    try {
      const data = await fetch(`/api/ecommerce/products?token=${token}`);
      const response = await data.json();
      setProducts(response.data?.items);
    } catch (e) {
      console.log(e);
    }
  }

  function renderProducts() {
    return (
      <>
        <h1>Products</h1>
        <div className="products">
          {products.map((product) => (
            <div>
              <img src={product.images[0]} alt={product.name} />
              <p>{product.title}</p>
            </div>
          ))}
        </div>
      </>
    );
  }

  useEffect(() => {
    if (token) {
      getProducts();
    }
    // eslint-disable-next-line
  }, []);

  return (
    <div className="App">
      {token ? (
        renderProducts()
      ) : (
        <a href="http://localhost:4000/connect">Click to Connect</a>
      )}
    </div>
  );
}

export default App;

54 lines of code (even less) is all it takes to get a products list from Shopify API (or any other e-commerce platform), using Common Ninja.

In the first 3 lines of the function we set an initial state for the token and products list. In case the user has already gone through the authentication process, the url of the page will include a unique token, generated by Common Ninja that allows him to access his store's resources.

In the useEffect hook, we make sure there's a token in the url. If there is, we're making an API call to our server.

useEffect(() => {
    if (token) {
      getProducts();
    }
}, []);

The getProducts function is using the fetch API to make a simple request to our server with the generated token:

async function getProducts() {
    try {
      const data = await fetch(`/api/ecommerce/products?token=${token}`);
      const response = await data.json();
      setProducts(response.data?.items);
    } catch (e) {
      console.log(e);
    }
}

The render function is also pretty straight forward. If there's a token in the URL, we show a list of products, else, we render a connect button that leads to the /connect route we mentioned before.

return (
    <div className="App">
      {token ? (
        renderProducts()
      ) : (
        <a href="http://localhost:4000/connect">Click to Connect</a>
      )}
    </div>
);

The renderProduct function simply iterates on the products list that the API returns, as described in the docs.

function renderProducts() {
    return (
      <>
        <h1>Products</h1>
        <div className="products">
          {products.map((product) => (
            <div>
              <img src={product.images[0]} alt={product.name} />
              <p>{product.title}</p>
            </div>
          ))}
        </div>
      </>
    );
}

And vualah! Here's the result:

Summary

In this article, we've learned how to create a Shopify app using React, NodeJS, and Common Ninja.

We saw how easy and simple it is to connect your app to Shopify, without being worried about authentication, APIs, and other complexities.

This is an example of a very simple app, but Common Ninja supports much complex use cases.

You can learn more about our e-commerce and payments APIs in our docs, and as always, we'll be more than happy to help you to get your app up and running so if you have any questions feel free to reach out!

Meanwhile, join our growing Discord community! 🔥

Common Ninja Platform News: Payments | New E-Commerce APIs

Daniel Sternlicht — Thu, 12 May 2022 08:41:01 +0000

We are very excited to share with you recent news and updates related to our developer platform. We are planning on posting these updates once a month, so stay tuned!

Just to remind you, the Common Ninja Developer Platform allows you to build & monetize apps for e-commerce platforms very easily. With our single e-commerce API you can build your app once, and integrate it with multiple platforms like Shopify, BigCommerce, Wix, WooCommerce, and more. There's no need to rebuild the app and make it work on every platform individually.

🎉 What’s New:

Payments
API updates
- Products
- Orders
- Customers

Payments

We are proud to present the brand new payments capabilities — that includes a simple interface that allows you to create payment plans for your app, connect them to popular payment providers like Stripe, PayPal, and Shopify app payment APIs, and dynamically create checkout URLs for your app’s users 🚀

Learn more about how it works in the docs.

API Updates

We’ve added 3 new e-commerce APIs:

Products - a new set of API endpoints for managing the store’s products resource.
Orders - with the new orders API you can create, update, and see store’s orders.
Customers - a simple API to consume a list of store’s customers.

You may learn more about all of the supported APIs here.

More exciting updates will be released soon so stay tuned!

The Problems With Building Apps for E-Commerce Platforms and Why We Built Common Ninja

Daniel Sternlicht — Mon, 02 May 2022 09:31:41 +0000

Let's start with the bottom line:

Building apps for e-commerce platforms is hard.

Background

E-Commerce platforms (such as Shopify, BigCommerce, Wix, WooCommerce, etc.) are great for people who want to build and manage shops online. They provide the best tools for shop owners to manage inventory, customize their storefront, and start making revenues from online orders.

But at the end, these platforms are limited, and this is why they allow developers to leverage their APIs and data to develop apps on top them.

These apps are being used by merchants and their customers and they are quite varied. From storefront widgets that increase conversions and enhance the user experience, to apps that collects data to improve inventory management, to social proof apps, and easy drop shipping.

E-Commerce apps are widely used by online merchants, and become very popular. How popular? Shopify says that in 2020 the average merchant installed 6 apps on his store, and that developer partners earned $233M in 2020 alone.

The thing is...

If you ask any developer who had an experience with building apps for e-commerce platforms "How was your experience?" you'll get the same answer: "It was a hell of a nightmare".

The Problems With E-Commerce Platforms For Developers

When you first start building an app you're entering a world of pain.

It starts with the documentation. In order to build an app you'll need to read. A lot. And while some platforms did a nice job with onboarding developers to their platform and documenting everything, others don't.

Once you find your way in the endless docs, and understand the different types of apps each platform allows you to build, the next thing will be to handle authentication.

Surprisingly, although most of the platforms are using OAuth, each one of them implemented the authentication flow differently so you'll need to learn exactly how it works on each platform separately while using tunnels (and in some cases to debug the code in production because you have to contact the platforms in order to change the auth endpoints).

I hope you're still here because there's more!

The next thing would be APIs. Let's take the Product resource as an example.

In Shopify a product object looks like that:

interface IShopifyProduct {
  id?: string;
  title?: string;
  body_html?: string;
  vendor?: string;
  product_type?: string;
  created_at?: string;
  updated_at?: string;
  handle?: string;
  variants?: {
    id?: string;
    product_id?: string;
    price?: string; // no unit supported in api
    weight?: number;
    weight_unit?: string;
  }[]
  images?: IShopifyProductImage[];
  status?: 'active' | 'archived' | 'draft';
  tags?: string;
}

interface IShopifyProductImage {
  product_id?: number;
  id?: number;
  title?: string;
  position?: number;
  created_at?: string;
  updated_at?: string;
  alt?: string;
  weight?: number;
  weight_unit?: 'kg' | 'lb';
  price?: number | string;
  src?: string;
  variant_ids?: string[];
  admin_graphql_api_id?: string;
}

And in BigCommerce like this:

interface IBigCommerceProduct {
  id?: number;
  name?: string;
  description?: string;
  date_created?: string;
  date_modified?: string;
  custom_url?: {
    url?: string;
  };
  type?: 'physical' | 'digital';
  weight?: number;
  price?: number;
  primary_image?: IBigCommerceProductImage;
  images?: IBigCommerceProductImage[];
}

interface IBigCommerceProductImage {
  image_file?: string;
  is_thumbnail?: boolean;
  product_id?: number;
  id?: number;
  description?: string;
  sort_order?: number;
  date_modified?: string;
  url_standard?: string;
  url_thumbnail?: string;
  url_tiny?: string;
}

While in Wix it's:

interface IWixProduct {
  id: string;
  name: string;
  slug: string;
  visible: boolean;
  weight: number;
  description: string;
  sku: string;
  productType: 'physical';
  priceData?: {
    currency?: string;
    price: number;
  };
  media?: IWixProductMedia;
  lastUpdated?: string;
}

There's no standardization, each platform sees things differently which is ok, unless you want to build an app that supports multiple platforms.

And finally - monetization.

If you're building an app, either for yourself or for a company you're working for, your end goal is obviously to see revenues out of it. However, while some platforms like Shopify and Wix are giving you some tools to monetize your app in different business models, all of the other platforms don't. Which means, that in addition to everything else you'll need to integrate payment solutions as well, and develop these integrations yourself.

Common Ninja: A New Era Of E-Commerce Apps Development

We know these problems very closely, since in the past 10 years we developed dozen of apps for website building and e-commerce platforms.

During these years we developed a lot of tools that helped us to decrease the development time of e-commerce platforms apps in 80%, which led us to establish Common Ninja and offer these tools to any developer out there 🎉

Common Ninja is a platform for building & monetizing e-commerce apps.

Our main offering is "One API to rule them all".

You'll work with a single API for consuming e-commerce resources such as products, orders, customers, etc. regardless the platform your user/merchant is using. You always know what you get, and if an e-commerce platform is changing their API, we take care of it behind the scenes so you won't have to.

In addition, with Common Ninja you'll be able to monetize your app flawlessly, create subscriptions based plans, and connect your app to popular payment providers like Stripe and PayPal.

Too good to be true? Probably. But this is us, and that's what we do 🙂

Want to learn more? go here:
https://www.commoninja.com/developers

If you have any feedback, question or comment, we're here.