Skip to main content
Version: 4.6.1-saas

Quick Start

Get started with NetFUNNEL 4 Node.js Agent in 5-10 minutes with this quick start guide.

What You Can Do with This Guide​

  • URL-Triggered Integration: Automatic queue control based on trigger rules
Choosing Integration Method

For detailed information about integration methods, refer to the Integration Methods Overview.

Prerequisites​

  • NetFUNNEL console access
  • Node.js project (Node.js 18 or higher)
  • Express or Nuxt framework

Step 1: Get Client ID and Secret Key​

  1. Go to NetFUNNEL Console
  2. Click the profile icon in the top right corner
  3. Select the Integration Credentials menu
  4. Copy Client ID and Secret Key

Step 2: Install Package​

Add Dependencies​

Add the following dependencies to package.json. The exact URL can be found in the Agent tab of the console.

{
  "dependencies": {
    "netfunnel-node-agent": "{{AGENT_URL}}"
  }
}

Install Package​

Run the following command from the project root:

npm install

Step 3: Apply Middleware​

Select and apply one of Express or Nuxt according to your project structure.

Express Method​

1. Create Middleware​

Create middleware/netfunnel-middleware.ts file:

import { Netfunnel } from 'netfunnel-node-agent';

export function netfunnelMiddleware(req, res, next) {
  Netfunnel.run(req, res).then(allowed => {
    if (!allowed) {
      return res.redirect(302, req._nfRedirect || '/');
    }
    next();
  });
}

2. Register Middleware in App​

Initialize NetFUNNEL and register middleware in app.ts:

import express from 'express';
import { router } from './routes.js';
import { netfunnelMiddleware } from './middleware/netfunnel-middleware.js';
import { Netfunnel } from 'netfunnel-node-agent';

const app = express();
const PORT = 3000;

/* NetFUNNEL Global Initialization */
Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',  // Client ID obtained in Step 1
  secretKey: '{{SECRET_KEY}}'  // Secret Key obtained in Step 1
});

app.use(netfunnelMiddleware);
app.use('/', router);

app.listen(PORT, () => {
  console.log(`[APP] listening on ${PORT} (NetFUNNEL ${Netfunnel.getVersion()})`);
});

Nuxt Method​

1. Create Middleware​

Create server/middleware/netfunnelAgent.ts file:

import { sendRedirect } from 'h3';
import { Netfunnel } from 'netfunnel-node-agent';

export default defineEventHandler(async event => {
  Netfunnel.initialize({
    clientId: '{{CLIENT_ID}}',  // Client ID obtained in Step 1
    secretKey: '{{SECRET_KEY}}'  // Secret Key obtained in Step 1
  });
  
  console.log('[APP] NetFUNNEL Version:', Netfunnel.getVersion());
  
  const allowed = await Netfunnel.run(event.node.req, event.node.res);
  
  if (!allowed) {
    const redirectUrl = (event.node.req as any)._nfRedirect || '/';
    console.log(`Redirecting now to: ${redirectUrl}`);
    return sendRedirect(event, redirectUrl);
  }
});

Step 4: Configure Trigger Rules​

  1. Create Segment in Console:

    • Go to NetFUNNEL Console → Projects → Segment → Create Segment
    • Enter segment name
    • Set entry status to Waiting
    • Set entry limit to 0 (for testing)

  2. Configure Trigger Rules:

    • Add rules in the Trigger Rules section
    • Validator: URL
    • Component: Path or URL
    • Match: Equals, Contains, StartsWith, EndsWith, etc.
    • Value: Enter URL path to apply (e.g., /checkout, /login)

Step 5: Test​

  1. Test Trigger Rules: Use the console's trigger rule test feature to verify that URLs match the rules
  2. Verify Waiting Room: Verify that the waiting room is displayed when accessing URLs that match the rules
  3. Verify Entry: Increase the entry limit to verify that entry works correctly

Need Help?​

  • Troubleshooting: Common issues and solutions
  • API Reference: Complete function specifications
  • Verify that the project/segment keys in the console match exactly