Overview
      Back to home
      1. Narrative Knowledge Base
      2. Integrations & Technical Guides
      3. Overview

      Building a Narrative Native App

      Building a Narrative Native App is an easy way for third party developers to extend the capabilities of the Narrative platform

      What is a Narrative Native App?

      Narrative Native Apps are applications bundled with a UI that can perform various actions on behalf of a user utilizing the Narrative API.

      Native Apps appear in the Narrative App Store, where users can choose to install an app, accept the terms of service for using the app, and begin using it immediately.

      Narrative Native App Components

      The following components make up a Narrative Native App:

      1. Tacklebox UI: A Vue-based component library that makes it simple to build and deploy user interfaces that match the look and feel of the Narrative platform. Read more about Tacklebox here. You can see also see and interact with the Tacklebox components in the sandbox here.
      2. App Manifest: A JSON blob that describes the required permissions, address of the app-hosted UI, configuration information and navigation pages required to render the app in the Narrative platform.
      3. Auth: Through an OAuth workflow, the Narrative Native App will be granted permissions to act on behalf of users that install the app.
      4. Narrative APIs: Based on the permissions they have been granted, Native Apps make calls

      Narrative Native App Types

      Functional Apps

      Extend Narrative platform functionality with a functional app. These are the most basic form of app, and are able to perform actions on the platform consistent with the API service permissions defined in their manifest.

      Egress Connector Apps

      Egress Connector Apps provide delivery of data from the Narrative platform to third party destinations. Egress connector apps are notified via an event bus when there is data that needs to be delivered downstream.

      Connector Apps additionally extend the functionality of other installed apps: Connector Apps appear in the “Destinations” section of the Dataset Manager app, and within the checkout workflow in Buyer Studio App, the Data Stream Marketplace, and elsewhere in the platform.

      For more information on Narrative Egress Connector Apps, visit the documentation here.

      Ingress Connector Apps

      Ingress Connector Apps provide new locations from which Narrative can ingest data.

      Channel Apps

      Channel Apps are apps that can take an existing Narrative Data Stream and deliver it to a specific channel (such as the AWS Data Exchange or The TradeDesk third party marketplace API).

      Because Data Stream data is only processed when a Data Stream subscription is created, Channel Apps must materialize Data Streams (create a new Dataset based on the Data Stream data) and deliver that dataset to their destination.

      External Function Apps

      External Function Apps provide access to a third party REST API service. Users will configure their API credentials and other necessary account information in the External Function App. External Functions can then be mapped to individual fields within Datasets, which will be augmented with data returned from the app.

      Narrative App Manifest

      The App Manifest provides the Narrative platform with the following information, which is required in order to render your app. You can see the full, up to date JSON schema required for an app here.

      App Manifests provide, at a minimum:

      • Base URLs for development and production sites where the app’s UI is hosted
      • Path to each of the pages in the app, for the Narrative Nav to render
      • Narrative API permissions that your app requests when users install the app. These are the Narrative API permissions your app can perform on the user’s behalf in order to function
      • Developer information so that users know who they are interacting with when they install your app.

      Narrative App User Interface

      App UI

      The user interface you host will appear within the Narrative UI. It will be available within the app when the user launches your app. It will have two components:

      • Narrative Navigation: All Narrative Native Apps share the Narrative navigation bar, which contains links to each page in your app as defined in your manifest (individual site page with a unique URL).
      • Developer-hosted iFrame: This is where the content of your hosted app UI will appear when a user navigates to one of the pages you define.

      narrative-native-app

      Tacklebox UI

      Your UI will utilize the Narrative UX design system and JS library Tacklebox, which makes developing applications against our API and style guide simple. You can see and interact with the Tacklebox components in the sandbox here.

      Narrative Native App OAuth Workflow

      In order to authenticate on behalf of a user, a Narrative Native App will use the Narrative OAuth workflow below. See the Narrative Auth service documentation for more details.

      In order to utilize the Narrative OAuth workflow, you will need:

      • Your app-specific client_id that was shared with you when your app was created
      • Your app-specific client_secret that was shared with you when your app was created

      Offline OAuth Workflow

      Utilize this workflow when your app needs to access the Narrative API but the action has not been triggered by a call to your UI.

      1. Send a request to the Narrative API Auth Service containing the client_id and client_secret
      2. Receive an access_token and a TTL for the access token, along with a refresh_token and a TTL for the refresh token.
      3. Use the access_token for all calls to the Narrative API until a refresh is required. If the access token expires, utilize the refresh token to get a new one.

      iFrame OAuth Workflow

      Utilize this workflow when the Narrative UI iFrame renders your app UI.

      1. The Narrative App Framework will call the UI with an API access_token that is authenticated to the App User’s company. The permissions and scope of this token are restricted to those that your App permissioned at install time.
      2. Tacklebox handles the API token natively if the App is called in an iFrame. After the app has been initialized in nioInitializeApplication, use the App's nioOpenAPI property on the global Vue object to access API services with any permissions granted to the app in the manifest. You can read more about that property here.

      How can I get started?

      To get started building, reach out to your account manager.