See also

SaaS Developers API Reference SaaS demo for JavaScript
23 Nov 2024 10:52 PM

Development quickstart

Start Developing

  1. Create Your Account
    Visit app.getconduit.app and register for a new account if you don't already have one.

  2. Setup the Organization Name
    Go to White Label. Enter the organization's name ("Your company name") and click the Save button. This action is required for this Demo. All other settings are optional.

  3. Obtain Your App Token
    Go to Get App Token to generate your master token. Save this token; you'll need it in the upcoming steps.

  4. Read API Reference

Explore Sample Projects

  • Dashboard embedded in your app with workspaces management (Python) See more
  • Dashboard embedded in your app (Client-side JavaScript). See more

Download and Run the SaaS Demo Python Demo Project

  1. Clone the Repository
    Download the demo project from the repository: https://github.com/cndt-app/saas_demo.

  2. Set Up the Environment
    Ensure you have Python 3.10+ and the Poetry package manager installed.
    Open your terminal, navigate to the project folder, and run:

    poetry install

  3. Project Structure
    The project includes two folders:

    • demo_app: Demonstrates API integration.
    • demo_server: Provides mock data for dashboards.

Start the Demo Data Server

  1. Launch the Demo Server
    Navigate to the demo_server folder:

    cd demo_server

    Start the server:

    poetry run python server.py

    The server will run at http://127.0.0.1:8008. You can modify the port in the server.py file.

  2. API Endpoint
    The server provides a CSV-formatted API response with the following columns:

    • Date
    • User ID
    • Campaign
    • Clicks
    • Install

    Parameters required for requests:

    • date_from: Start date in ISO format (YYYY-MM-DD).
    • date_to: End date in ISO format (YYYY-MM-DD).
    • user_id: User ID (used as-is in the response).

  3. Expose the Server Publicly (ngrok)

    • Register and Install ngrok
      Sign up at ngrok.com and follow the Getting Started guide.

    • Start ngrok
      Run:

      ngrok http 8008

      This generates a public URL (e.g., http://<your-ngrok-domain>.ngrok.io). Save this URL for the next step.

Configure a Connection in Conduit

More details on Remote HTTP Connection

  1. Set Up a Remote HTTP Connection
    In the Conduit sidebar, click Connections.
    Search for "Remote HTTP" and click Connect.

    • Connection Name: e.g., Demo Server.
    • Enable Share to Workspaces.
    • Request Settings:
    • URL: Paste your ngrok URL (e.g., http://<your-ngrok-domain>.ngrok.io).
    • Method: GET.

  2. Request Parameters: Add:

    • date_from → {{date_from}}.
    • date_to → {{date_to}}.
    • user_id → {{user_id}}.

  3. Define Data Columns
    Describe the returned CSV format:

    • Date: Dimension, DATE.
    • User ID: Dimension, STRING.
    • Campaign: Dimension, STRING.
    • Clicks: Metric, INTEGER.
    • Spend: Metric, MONEY.

clipboard-2024-11-19-21-22-17-658Z.png
Click Save.

Create a Dashboard Template

  1. Set Up the Dashboard
    In the sidebar, go to Dashboards and click Create Dashboard.
    Name your dashboard, e.g., Dashboard Template.

  2. Add Widgets

    • Time Series Chart:
      • Connection: Select Remote HTTP API. You've created it previously.
      • Endpoint: Choose Demo Server.
      • Y-Axis: Clicks.
      • X-Axis: Date.

clipboard-2024-11-19-21-31-11-279Z.png

  • Add another widget for the Spend metric.

Run the Demo Application

  1. Start the Demo App Server
    Navigate to the demo_app directory:

    cd demo_app

    Launch the server using the command:

    poetry run python manage.py runserver

    The server will be available at http://127.0.0.1:8000.

  2. Log In to the Demo App
    Open http://127.0.0.1:8000 in your browser. You’ll see the login screen.

    • Paste the master token you obtained earlier in Step 1. If needed, retrieve it again from Get App Token.
    • Click Sign In.

clipboard-2024-11-19-21-40-12-196Z.png

Upon logging in, you'll see a list of your workspaces. If you’re using a new account, this list will initially be empty.

API Overview
The demo app retrieves the list of workspaces by making an API request:

curl -X GET \
https://api.getconduit.app/v2/workspaces/ \
-H "Authorization: Bearer <master_token>"

Replace <master_token> with your master token.

Create a Workspace

Add a Workspace

  • Click the Create Workspace button.
  • Provide a name for the workspace.
  • Fill in the ext_id field with a unique identifier (any text value). The ext_id value substitutes the {{user_id}} macro in API requests.

clipboard-2024-11-19-21-43-49-752Z.png

Tip:Use the ext_id as the user's authorization token for authenticating with your Remote HTTP API connection.

Click Create.

API Overview
When creating a workspace, the demo app sends the following API request:

curl -X POST \
https://api.getconduit.app/v2/workspaces/ \
-H "Authorization: Bearer <master_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "<workspace_name>",
  "ext_id": "<ext_id>"
}'
  • <workspace_name>: Name of the workspace.
  • <ext_id>: External ID of the workspace.

Response:

[
  {
    "id": "...",    # Internal workspace ID
    "name": "...",  # Workspace name
    "ext_id": "...", # External ID
    "token": "..."  # Authorization token for the workspace
  },
  ...
]

Clone the Dashboard

Copy a Dashboard Template

  • After creating the workspace, you’ll return to the workspace list.
  • Locate the workspace and click Dashboards.
  • In the Master Account Dashboards section, find the Dashboard Template.
  • Click the Clone button to copy the template into the child workspace. The dashboard will now appear in the Workspace Dashboards section.

API Overview

  • To list dashboards, the app sends:

    curl -X GET \
https://api.getconduit.app/v2/dashboards/ \
-H "Authorization: Bearer <master_token>"

  • To clone a dashboard into a workspace, the app sends:

    curl -X POST \
https://api.getconduit.app/v2/dashboards/<dashboard_id>/clone \
-H "Authorization: Bearer <master_token>" \
-H "Content-Type: application/json" \
-d '{
  "workspace_id": "<workspace_id>"
}'

    Response:

    {
  "id": "...",     # Internal dashboard ID
  "name": "...",   # Dashboard name
  "url": "..."     # Embed link for iframe
}

Open a Child Workspace Dashboard

View the Dashboard

  • In the Workspace Dashboards section, click the Open button next to the cloned dashboard.
  • The dashboard will open, displaying graphs with data.
    clipboard-2024-11-19-22-08-33-805Z.png
    API Overview
    To fetch the public URL of the dashboard, the app makes this API request:
curl -X GET \
https://api.getconduit.app/v2/dashboards/<dashboard_id>/share/ \
-H "Authorization: Bearer <workspace_token>"

Response:

{
  "url": "https://app.getconduit.app/r/public/dashboard/..."
}

This URL can be embedded in your application using an iframe.

Conclusion

You’ve successfully completed the demo app walkthrough! You can now integrate, manage, and explore dashboards using Conduit’s API and tools.

close