Narrativ API Developer Documentation

At Narrativ, we transform real content into organic ads that are not impacted by AdBlock. Our goal is to lift publisher revenues from organic content through real-time bidding and machine learning solutions. The Narrativ API allows you to access our technology without having editors create manual links. Create an API key to get started or browse the full documentation below:

API Authentication

Creating an API key

To use the Narrativ API, you will need to create an API key for your user account. Navigate to the Developer Options page and follow the directions there.

Using your API key

Unless otherwise indicated, Narrativ API requests must include a valid API key. Send your API key in the HTTP Authorization header, prefixed with the scheme NRTV-API-KEY. For example:

curl -i -H 'Authorization: NRTV-API-KEY Sy8xLzE2MTE3MDIxNzY3NDM0OTc0MDcv' \
    https://api.narrativ.com/api/v1/tokeninfo/

HTTP/1.1 200 OK

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "token_id": 1001,
      "uid": 2,
      "description": "My API Key",
      "datetime_created": "2017-07-25T20:58:38Z",
      "datetime_updated": "2017-07-25T20:58:38Z",
      "datetime_active": "2017-07-25T20:58:38Z",
      "datetime_expires": null,
      "datetime_last_used": null,
      "is_enabled_by_user": true
    }
  ]
}

If a valid API key is not sent, the server will return an HTTP 401 error:

curl -i -H 'Authorization: NRTV-API-KEY TestInvalidAPIKey' \
    https://api.narrativ.com/api/v1/tokeninfo/

HTTP/1.1 401 UNAUTHORIZED

{
  "info": {
    "error": true,
    "status": 401
  },
  "data": [],
  "error": {
    "code": 4302,
    "message": "Invalid API token",
    "data": null
  }
}

Keeping your account secure

Remember to keep your API key secret, since anyone who has it can use it to access your Narrativ account. If you ever lose your API key, you can visit the Developer Options page to disable it and create a new one.

Sending and Receiving Data

Data formats

The API is accessed via HTTPS at https://api.narrativ.com/ . Use JSON when sending data to API endpoints that require it. Remember to specify Content-Type: application/json in the request headers.

When sending URLs, make sure to use the complete link, including the http:// or https:// part.

Timestamps are formatted according to the ISO 8601 standard, using the UTC time zone, and are precise to the nearest second. For example, 2017-07-26T19:48:25Z.

Response fields

API responses will always contain a few standard fields:

  • info: An object containing general information about the request/response:

    • error: true if something went wrong with the API request, or false if everything is okay.

    • status: The HTTP status code, repeated here for convenience.

  • data: A list of resources returned by the request.

  • error: If an error occurred, this object will contain detailed information about the problem.

    • code: A number categorizing the error.

    • message: A string describing the specific error.

Dynamic API

ClickMate

Overview

ClickMate provides a wrapper that you can use on any link to convert it, on the fly, to a SmartLink. This means that the link will go through our matching process, and on future clicks will work through our real time auction system and will re-route to the most beneficial advertiser.

Query Params

URL Path Parameter

Type

Description

url

string(2048)

Required The URL of the target link (must be URL encoded!). Without this, users will see an error page

article_url

string(2048)

Required The canonical URL of the article your link is coming from (must be URL encoded!).

article_name

string(100)

Required The readable name or title of the article your link is coming from (not a numeric identifier).

publisher_slug

string(64)

Required The slug provided by your Narrativ account rep. Without this we will not know what account to monetize clicks for.

exclusive

Integer

Optional Set this to 1 if you want to ensure that this particular link only goes to the original retailer.

u1

string(2048)

Optional Arbitrary tracking parameter that you may apply to links for your own tracking (will be passed to our stats).

URL Encoding

All parameters must be URL encoded. See URL Encoder.

Example Code

In Javascript:

var url = 'https://merchant.example/product1234';
var slug = 'myacct';
var articleName = document.title;
var articleUrl = window.location.href;
var clickmateUrl = 'https://shop-links.co/link?url=' + encodeURIComponent(url) +
   '&publisher_slug=' + slug +
   '&article_name=' + encodeURIComponent(articleName) +
   '&article_url=' + encodeURIComponent(articleUrl);

Multi-Match Exclusive API

Overview

This API takes a product identifier and matches the product to all instances of this product in our merchant network. The output will include matched product information, merchant information, and Narrativ links which are exclusively matched to each merchant. Please note that by using this API, Narrativ’s bidding algorithm will be bypassed. This endpoint is typically used for multiple links or multiple buttons per product.

Request

GET /api/v1/product_match/clickmate/exclusive_links/

Query Param

Type

Description

publisher_slug

string(64)

(Required) The account identifier provided by your Narrativ account rep.

gtin

string(14)

Product descriptor (Optional - see below): the GTIN of the product - used as an identifier to find matches in Narrativ merchant network. Please note, this is sometimes referred to as the UPC of the product.

sku

string(255)

Product descriptor (Optional - see below): the SKU of the product - used as an identifier to find matches in Narrativ merchant network

article_url

string(2048)

Article info (Required): The URL of the article or page the link is published on (must be URL encoded!)

article_name

string(100)

Article info (Required): The name or title of the article or page the link is published on

Identifier Parameters

Please Note: at least one identifier (gtin, sku) must be present for this endpoint.

Response

The response data consists of the list data, with each entry having the following structure:

Field Name

Type

Description

best_effort_cpc

float

Point in time prediction of the CPC for the merchant publisher pairing in USD

clickmate_link

string

The monetized Narrativ link which is exclusively matched to each merchant

product_information

json
Product details
  • brand

    • string

    • The retrieved product’s brand

  • gtin

    • string

    • The retrieved product’s GTIN

  • image_url

    • string

    • The retrieved product’s image URL

  • in_stock

    • boolean

    • If the product is currently in stock or not

  • price

    • string

    • The price of the retrieved product in USD

  • product_name

    • string

    • The retrieved product’s name

  • merchant_name

    • string

    • The name of the merchant selling the retrieved product

URL Encoding

All parameters must be URL encoded. See URL Encoder.

Example Requests

GET /api/v1/product_match/clickmate/exclusive_links/?publisher_slug=myacct&gtin=77777777777&article_name=Top+5+Products&article_url=https%3A%2F%2Fwww.narrativ.com%2Farticles%2Ftop5products

GET /api/v1/product_match/clickmate/exclusive_links/?publisher_slug=myacct&sku=00000000&&gtin=88888888888888&article_name=Top+5+Products&article_url=https%3A%2F%2Fwww.narrativ.com%2Farticles%2Ftop5products

GET /api/v1/product_match/clickmate/exclusive_links/?publisher_slug=myacct&sku=00000000&article_name=Top+5+Products&article_url=https%3A%2F%2Fwww.narrativ.com%2Farticles%2Ftop5products

Example Response

{
    "data": [
        {
            "product_information": {
                "price": "15.99",
                "product_name": "Example Product",
                "in_stock": true,
                "gtin": "55555555555555",
                "image_url": "https://merchant.example/path/to/image_url",
                "brand": "Example Brand",
                "merchant_name": "Example Retailer"
            },
            "clickmate_link": "https://shop-links.co/link/?url=https%3A%2F%2Fwww.merchant.example%2Fproduct%2F123%0Aexclusive=1&publisher_slug=myacct",
            "best_effort_cpc": 0.50,
        }
    ]
}

Merchant Feeds

Overview

Narrativ provides the ability for our publisher partners to download merchant feeds in a standardized format for monetization. This enables product data to be integrated into your CMS, allowing for more control over monetization decisions and integration of multi-button formats.

Feed Schema

Please note: all fields are nullable due to incomplete and/or inapplicable data. The feeds will only include products that are in-stock at time of file generation.

Field Name

Type

Description

brand

String

Name of product brand

colors

List<string>

List of colors for the product (if applicable)

currency

String

Currency code of price

description

String

Description of the product

google_product_category

List<string>

List of Google Product categories for this product

gtin

String

Global trade item number; a unique product identifier

image_url

String

URL of product image

item_group_id

String

ID for a group of Item IDs

item_id

String

Individual Item ID

manufacturer

String

model

String

mpn

String

name

String

Product name

price

Float

Regular price of product

sale_price

Float

Sale price of product

sizes

List<string>

List of sizes for the product (if applicable)

sku

String

Stock keeping unit; a unique product identifier to specific retailer

store_page_url

String

Product page URL

Formatting

Please make note of below formatting standards when ingesting the product feeds:

  • All headers are wrapped in double quotes

  • All string type fields are wrapped in double quotes

  • All empty fields are denoted by empty double quotes

Feed Delivery

Narrativ supports two methods of feed delivery:

Amazon S3: Feeds will be delivered in a shared S3 bucket configured to have a sub-folder for each merchant.

If the publisher has their own AWS account, we will configure a shared S3 bucket that can be owned by either party. Access will be managed using IAM roles.

If the publisher does not have their own AWS account, we will configure a shared S3 bucket accessed by secret key & access key. Credentials will be shared in a 1pass vault for security purposes.

SFTP: Feeds will be delivered to publisher’s SFTP location.

Configuring the URLs

Product URLs contained in feed must be wrapped in our click wrapper (Clickmate) before publishing to the site. This ensures the link is properly monetized with Narrativ tracking appended on click.

Publisher JS Tag

It is recommended to add our Publisher JS Tag for this integration method. The JSTag allows for real-time optimization utilizing dynamic links and dynamic button displays as detailed in the linked documentation page. Additionally, the JS Tag unlocks higher rates by enabling impressions tracking and post-impression attribution.

Getting Started

Please contact your account manager or support@narrativ.com and we will reach out with next steps.

UTM Source Tracking

Overview

Narrativ leverages utm_source to better segment traffic from syndicated channels, such as Apple News, AMP, or Social. This is configured as a simple url parameter appended to Narrativ links. Please note, this will not affect the link’s monetization in any way.

Auctions

Usage

The Auction API runs an auction on a SmartLink and returns an updated destination URL for the link. You can use this API to write your own custom publisher Javascript tags. Be sure to read through the tutorial before proceeding.

Note

The Auction API does not require client authentication, but may be subject to rate-limiting if called an extreme number of times from the same origin.

Run Auction

Request

GET /api/v1/auction/

Query Param

Type

Description

a

string

Auction ID. This is the number at the end of your SmartLink. For example, the SmartLink https://shop-links.co/1522995078114976993 has the Auction ID 1522995078114976993.

t

integer

Cache-busting parameter. Set this to a randomly-generated number to prevent HTTP caching of the auction request and response.

uuid

string

Page Session UUID. The UUID v4 value that your client has generated for the current page session.

Response

Auction result data

Field Name

Type

Description

auction_result . id

string

A unique identifier for the result of the auction.

auction_result . product

object

Product information for the advertiser that won the auction.

auction_result . redirect_url

string

The new destination URL for the SmartLink.

auction_result . tracker_urls

object

Third-party event tracker URLs for this SmartLink placement. Your client is responsible for firing all trackers listed here when the applicable event(s) occur.

impression_pixel_url

string

The primary impression event tracker URL for this SmartLink placement. Your client is responsible for firing this tracker after receiving the auction response.
Product information (auction_result.product)

Auction API responses may provide the following information about the advertiser (retailer/merchant) and the product page that will be receiving the click on the rewritten SmartLink:

Field Name

Type

Description

id

integer

A unique identifier for the product that the destination URL refers to.

name

string

The name of the product being sold.

price

string

The price of the product being sold, in USD.

url

string

The raw URL of the product page, for display purposes. (Do not rewrite the SmartLink with this URL.)

image_url

string

The image URL of the product being sold, for display purposes.

is_in_stock

boolean

The stock status of the product being sold.

merchant . id

integer

A unique identifier for the advertiser.

merchant . canonical_host

string

The host part of the advertiser’s website URL, for display purposes.

merchant . name

string

The name of the advertiser.

merchant . url

string

The full URL for the advertiser’s home page.
Third-party event trackers (auction_result.tracker_urls)

Auction API responses may include the following set of third-party event trackers that apply to your SmartLink placement:

Event Tracker Type

Event Description

impression

Signals that at least one occurrence of this SmartLink has been loaded on the page. You may fire this event tracker immediately after receiving the auction response.

viewable_impression

Fire this event tracker once any occurrence of this SmartLink is scrolled into view on the page.

Tracker URLs may include the template parameter {RAND}, which must be replaced with a randomly-generated number for cache-busting prior to firing the tracker.

Do NOT fire a third-party event tracker more than once per page for the same event, even if the same SmartLink appears multiple times on that page.

Example

GET https://api.bam-x.com/api/v1/auction/
    ?a=1629223267830557131
    &t=1517261651
    &uuid=8132ac19-109a-466e-8037-540a9bd12798

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "auction_result": {
        "id": "1629224701990881693",
        "auction_id": "1629223267830557131",
        "redirect_url": "https://api.bam-x.com/api/v1/redirect/?a=1629223267830557131&uid_bam=1629224701957143181&ar=1629224701990881693&url=https%3A%2F%2Fwww.amazon.com.example%2F&uuid=8132ac19-109a-466e-8037-540a9bd12798",
        "product": {
          "merchant": {
            "url": "https://www.amazon.com/",
            "canonical_host": "amazon.com",
            "id": 2186,
            "name": "Amazon"
          },
          "bamx_product_category_id": 3,
          "name": "Designer Handbag",
          "url": "https://www.amazon.com.example/product/1234",
          "image_url": "https://www.static.amazon.example/image/path/1234",
          "is_in_stock": true,
          "price": "299.99",
          "id": 8030310
        },
        "tracker_urls": {
          "viewable_impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=lv;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
            "https://ad.atdmt.com.example/1111?r={RAND}"
          ],
          "impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=li;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
            "https://ad.atdmt.com.example/2222?r={RAND}"
          ]
        }
      },
      "impression_pixel_url": "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?"
    }
  ]
}

AMP

Narrativ’s smartlink technology can be deployed to Google AMP pages. To enable Smartlinks on your AMP page, please notify Narrativ and then integrate the amp-smartlinks tag into your AMP pages, as described below.

Usage

In addition to the docs below, you may reference the information provided on AMP’s Github page.

AMP Smartlinks searches the AMP article for Smartlink-compatible URLs, automatically creating new SmartLinks that do not already exist. AMP Smartlinks is our full Linkmate offering in AMP.

Your account must be a member of our LinkMate program to use this feature. For more information about this program, feel free to contact us

  • Make sure to replace “ACCOUNT NAME” with your Narrativ account name. If you don’t know your account name, please reach out to your account manager or contact us.

<!doctype html>
<html ⚡>
<head>
  ...
  <meta name="amp-link-rewriter-priorities" content="amp-smartlinks amp-other-affiliate">
  <script async custom-element="amp-smartlinks" src="https://cdn.ampproject.org/v0/amp-smartlinks-0.1.js"></script>
  ...
  <script async src="https://cdn.ampproject.org/v0.js"></script>
</head>
<body>
    ...
    <amp-smartlinks
        layout="nodisplay"
        nrtv-account-name="ACCOUNT NAME"
        linkmate>
    </amp-smartlinks>
    ...
</body>
</html>

AMP Attribute values

Attribute Name

Type

Required

Description

nrtv-account-name

string

True

Your Narrativ account name.

linkmate

Boolean

False

The presence of this attribute determines if Linkmate is true or not.

exclusive-links

Boolean

False

The presence of this attribute determines if exclusive-links will be made or not.

link-attribute

string

False

Where you store the outbound link value, if it is not in href.

link-selector

string

False

CSS selector for selecting links from the page. Default value is a

  • To make all LinkMate links on the page exclusive, you can use the exclusiveLinks flag in the amp-smartlinks element. Exclusive links means that links will only be matched to the original merchant.

<amp-smartlinks
    layout="nodisplay"
    nrtv-account-name="ACCOUNT NAME"
    linkmate
    exclusive-links>
</amp-smartlinks>

  • If you are running amp-smartlinks with other affiliate tags then you have to specify the following element with the ordering you want your links to be monetized.

...
<meta name="amp-link-rewriter-priorities" content="amp-smartlinks amp-other-affiliate">
...
</head>
<body>
...
  <amp-smartlinks
      layout="nodisplay"
      nrtv-account-name="ACCOUNT NAME"
      linkmate>
  </amp-smartlinks>

  • If you do not use href attributes to specify the outbound links, then make sure to specify link-attribute in the element. Also, if you want to limit the selector used to detect links use link-selector.

<amp-smartlinks
    layout="nodisplay"
    nrtv-account-name="ACCOUNT NAME"
    linkmate
    link-attribute="data-vars-outbound-link"
    link-selector="a.links-to-be-monetized">
</amp-smartlinks>

  • To disable LinkMate on a specific link, add #donotlink to the end of the URL

http://exampleproductlink.example/supercoolproduct/ref=ods?#donotlink

  • To indicate an exclusive link, add #locklink to the end of the URL

http://exampleproductlink.example/supercoolproduct/ref=ods?#locklink

Publisher Events

Note

The Events API does not require client authentication, but may be subject to rate-limiting if called an extreme number of times from the same origin.

Submit New Publisher Events

Request

POST /api/v1/events/<event_category>/<event_type>/
Available event categories and types

Event Category

Event Type

Description

impressions

page_impression

Marks the beginning of a page session. Fire this event once your page has loaded and you have generated your Page Session UUID.

impressions

bam_link_impression

Signals that a SmartLink (Bam Link) has loaded on the page.
Event request payload

Field Name

Type

Description

organization_type

string

This field must always be set to publisher.

organization_id

integer

Your publisher ID.

user

object

Information about the current visitor to your site, for analytics.

events

list[object]

Data for each event that you are submitting. You may submit up to 100 events per API call.
User information fields

You must generate and assign a Page Session UUID to your events. The other fields listed here provide context about your site visitor and your article for deeper analytics.

Field Name

Type

Description

page_session_uuid

string

The UUID v4 value that your client has generated for the current page session.

source_url

string

The URL of the current page.

previous_url

string

Optional. The HTTP Referer URL.
Event data for page impressions

Page events currently require no additional data. In the events list, send an empty object {}.

Response

Empty response. An HTTP 201 status code indicates successful event submission.

Examples

Submitting a single page impression event:

POST /api/v1/events/impressions/page_impression/

{
  "organization_type": "publisher",
  "organization_id": 1,
  "user": {
    "page_session_uuid": "8132ac19-109a-466e-8037-540a9bd12798"
  },
  "events": [
    {}
  ]
}

HTTP/1.1 201 CREATED
Content-Length: 0

Submitting a group of two SmartLink impression events using a single request:

POST /api/v1/events/impressions/bam_link_impression/

{
  "organization_type": "publisher",
  "organization_id": 1,
  "user": {
    "page_session_uuid": "8132ac19-109a-466e-8037-540a9bd12798"
  },
  "events": [
    {
      "auction_id": "1522995078114976993"
    },
    {
      "auction_id": "1522738266273264784"
    }
  ]
}

HTTP/1.1 201 CREATED
Content-Length: 0

Statistics

Fetches statistics for a given publisher over a specified date range.

Get statistics grouped by articles and merchant per day

Request

GET /api/v1/publishers/<pub_id>/stats_by_article_merchant_daily/

URL Path Parameter

Type

Description

pub_id

integer

Your publisher ID.

Query Param

Type

Description

date_from

string

Required: The starting date to collect statistics, as an ISO 8601 compliant string. Ex: ‘2018-01-01’, ‘2015-03-11’

date_to

string

Required: The end date to collect statistics, as an ISO 8601 compliant string. Must be greater than date_from.

limit

integer

Optional: The upper limit on the number of rows returned by this query. The current default and maximum is 10000.

order_by

string

Optional: Order the returned rows by the specified column. Current default is clicks. Acceptable values are:

  • article_id

  • advertiser_attributed_sales

  • pub_earnings

  • merch_id

  • impressions

  • advertiser_attributed_revenue

  • event_date

  • clicks

out_of_network

boolean

Optional: If set to true, return data for other networks in addition to the Narrativ network. Default value is false.

Response

The response data consists of the list stats, with each entry having the following structure:

Field Name

Type

Description

advertiser_name

string

The full name of the advertiser. Will default to null if the advertiser is outside the Narrativ merchant network.

article_name

string

The full name of the article.

advertiser_attributed_sales

integer

The total number of sales attributed to the advertiser.

pub_earnings

string

The amount of money earned by the publisher in USD. (Ex: ‘12345.67’)

article_id

integer

The ID of the particular article.

article_url

string

The URL of the particular article.

merch_id

integer

The ID of the merchant.

impressions

integer

The total number of page impressions.

advertiser_attributed_revenue

string

The total amount of revenue attributed to the advertiser in USD. (Ex: ‘100.00’)

pub_id

integer

The ID of the publisher.

event_date

string

The date associated with this entry.

clicks

integer

The total number of clicks.

Examples

Get statistics grouped by articles and merchants per day between 2018-03-11 and 2018-03-12:

GET /api/v1/publishers/1/stats_by_article_merchant_daily/

{
    "date": {
        "date_from": "2018-03-11 00:00:00",
        "date_to": "2018-03-12 00:00:00"
    },
    "pub_id": 1,
    "stats": [
        {
            "advertiser_name": "Merchant Name A",
            "article_name": "Some article name",
            "advertiser_attributed_sales": 60,
            "pub_earnings": "10.25",
            "article_id": 1,
            "article_url": "https://www.merchant-name-a.com/article?=1",
            "merch_id": 10,
            "impressions": 200,
            "advertiser_attributed_revenue": "150.00",
            "pub_id": 1000,
            "event_date": "2018-03-11",
            "clicks": 500
        },
        {
            "advertiser_name": "Merchant Name A",
            "article_name": "Another article name",
            "advertiser_attributed_sales": 600,
            "pub_earnings": "99.75",
            "article_id": 1,
            "article_url": "https://www.merchant-name-a.com/article?=2",
            "merch_id": 10,
            "impressions": 700,
            "advertiser_attributed_revenue": "350.00",
            "pub_id": 1000,
            "event_date": "2018-03-12",
            "clicks": 200
        }
    ]
}

Javascript Tag Basics

The Narrativ platform collects data on Publisher and Advertiser websites to allow the system to make intelligent decisions that optimize SmartLink auctions. By analyzing content that readers are viewing and clicking, and taking their purchase history into account, Narrativ ensures that consumers are matched with merchants who carry the products they want.

Narrativ Publisher Tag

Functionality

The Narrativ publisher tag is a light-weight tag that has two operational modes: Audit Mode and Active Mode.

Audit Mode

Audit Mode allows us to size the opportunity for Out of Stock link repair and scopes the size of integration. This mode also allows us to identify additional retailers that sell your recommended products, diversifying your content monetization.

Active Mode

Active Mode contains the features of Audit Mode, and enables Narrativ’s link monetization features. The active tag finds all eligible commerce links on the page and runs Narrativ tracking and optimization. Reporting on links can be found in the Narrativ dashboard.

Audit Mode Implementation

Getting the Narrativ tag to successfully run in Audit Mode is a simple process. Copy and paste the following Javascript snippet in the HEAD section of all your site’s pages.

  • Make sure to replace ACCOUNT NAME with your Narrativ account name.

  • Need to know your Narrativ account name? Log into dashboard.narrativ.com and go to setup to see the snippet customized with your account info, or reach out to your account manager for support as needed.

  • See if it’s working: There is a checker on your “setup” page where you can insert your site URL to verify if the Narrativ Publisher tag is correctly installed.

<script type="text/javascript">
    (function(window, document, account) {
        window.skimlinks_exclude = ["shop-links.co", "shop-edits.co"];
        window.NRTV_EVENT_DATA = { donotlink: true };
        var b = document.createElement("script");
        b.type = "text/javascript";
        b.src = "https://static.narrativ.com/tags/" + account + ".js";
        b.async = true;
        var a = document.getElementsByTagName("script")[0];
        a.parentNode.insertBefore(b,a);
    })(window, document, "ACCOUNT NAME");
</script>

Active Mode Implementation

Updating the tag from Audit Mode to Active Mode is a small, one-line change. Simply remove the following line from the audit tag to enable Active Mode:

window.NRTV_EVENT_DATA = { donotlink: true };

If you aren’t currently using the tag in Audit Mode, copy and paste the following Javascript snippet in the HEAD section of all your site’s pages.

  • Make sure to replace ACCOUNT NAME with your Narrativ account name.

  • Need to know your Narrativ account name? Log into dashboard.narrativ.com and go to setup to see the snippet customized with your account info, or reach out to your account manager for support as needed.

  • See if it’s working: There is a checker on your “setup” page where you can insert your site URL to verify if the Narrativ Publisher tag is correctly installed.

<script type="text/javascript">
    (function(window, document, account) {
        window.skimlinks_exclude = ["shop-links.co", "shop-edits.co"];
        var b = document.createElement("script");
        b.type = "text/javascript";
        b.src = "https://static.narrativ.com/tags/" + account + ".js";
        b.async = true;
        var a = document.getElementsByTagName("script")[0];
        a.parentNode.insertBefore(b,a);
    })(window, document, "ACCOUNT NAME");
</script>

Please Note: The tag identifies each link in our system by the product url and page url. If your website uses dynamic values (such as user or session id) in either the product or page urls please inform your Narrativ representative to ensure correct functionality

Active Tag Capabilities: Dynamic price and merchant names (Out of Stock optimization)

As discussed above, one main benefit of the Narrativ JsTag is to find commerce links on your site and run the auctions on page load. For publishers whose commerce buttons or article content mention the merchant’s name and product price (“$5 at Nordstrom”), this feature will enable you to update those values dynamically.

After an auction completes, the Narrativ tag will write the output of the auction to the data-bamx-auction attribute. In that attribute, you can find product price, retailer name, image_url, etc. to update the article information for a link. A full list of the auction response can be found on our Auction page.

Updating Your Buttons

Below is an example JS snippet that will create a MutationObserver, on all relevant links on your article, which trigger after our auction runs. Please note, the code below assumes monetized-links is a pre-existing identifier. If there is no identifier you may use document.querySelectorAll("a[data-bamx-auction]") instead.

 1const anchorNodes = [...document.querySelectorAll('a.monetized-links')];
 2const config = {attributes: true};
 3
 4for (let i = 0; i < anchorNodes.length; i++) {
 5  let anchor = anchorNodes[i];
 6
 7  const logFunction = (mutationList, observer) => {
 8    for (let j = 0; j < mutationList.length; j++) {
 9      const mutation = mutationList[j];
10
11      if (mutation.type === 'attributes' && mutation.attributeName === 'data-bamx-auction') {
12        console.log('Narrativ Auction has finished. Update display values now');
13        console.log(anchor.getAttribute('data-bamx-auction'));
14        // Your custom update function here.
15      }
16    }
17  };
18
19  const observer = new MutationObserver(logFunction);
20  observer.observe(anchor, config);
21}

Merchant Checkout Tracking: U1 Parameter Support

The Narrativ publisher tag also provides user ID tracking for clicks and checkouts via an appendable U1 Parameter.

To add the U1 parameter to Narrativ events, add the following snippet to your Narrativ tag script:

window.BAMX_EVENT_DATA = { u1Param: yourU1Param };

Replace yourU1Param with your U1 Parameter variable

Once added, your Javascript tag should look like this:

<script type="text/javascript">
    (function(window, document, account) {
        window.skimlinks_exclude = ["shop-links.co", "shop-edits.co"];
        window.BAMX_EVENT_DATA = { u1Param: yourU1Param };
        var b = document.createElement("script");
        b.type = "text/javascript";
        b.src = "https://static.narrativ.com/tags/" + account + ".js";
        b.async = true;
        var a = document.getElementsByTagName("script")[0];
        a.parentNode.insertBefore(b,a);
    })(window, document, "ACCOUNT NAME");
</script>

The U1 Parameter can be included in click and order reports. Please contact your account manager or support@narrativ.com for more details.

Note: This implementation is specific for Linkmate integrations. For using U1 Parameters with a Clickmate integration, see Clickmate Query Parameters.

Narrativ Brand Tag

What is it?

The Narrativ Brand Tag is a lightweight javascript tag that enables partners to maximize their performance and unlock valuable article and product level insights in a customized dashboard. Only clients with Narrativ’s Brand Tag can optimize their campaigns by ROAS and see more comprehensive metrics like revenue and RPC.

Please note: data collection by the brand tag does not contain personally identifiable information (PII) and is in compliance with GDPR and CCPA.

How it Works

The Narrativ Brand Tag is responsible for handling two types of events: page impressions and checkouts.

Page Impressions

Page impression events enable Narrativ to ensure attribution for our partners. These events should be fired on every page that doesn’t contain PII.

Checkouts

Checkout events allow Narrativ to accurately capture revenue and conversions in real time. The data gathered by checkout events also powers an experience publishers rely on to track top sellers and give better product recommendations on their articles.

Checkout events should be fired on your site’s Order Confirmation Page, or the page that loads immediately after they’ve successfully purchased their items.

Please note: Similar to Page Impression, Checkouts are in compliance with GDPR and CCPA and does not capture personally identifiable information (PII). Additionally, since the tag runs asynchronously in the background, there is no impact to the page load time.

Implementation

Page Impression Events

Getting the Narrativ Brand Tag to fire page impression events is a simple process. Copy and paste the following Javascript snippet in the HEAD section of all your site’s pages that don’t contain PII.

  • Make sure to replace ACCOUNT NAME with your Narrativ account name.

  • Need your Narrativ account name? Reach out to your growth manager or solutions@narrativ.com for assistance.

<script type="text/javascript">
    (function(account) {
        try {
            var b = document.createElement("script");
            b.type = "text/javascript";
            b.src = "https://static.narrativ.com/tags/" + account + ".js";
            b.async = true;
            var a = document.getElementsByTagName("script")[0];
            a.parentNode.insertBefore(b, a);
        } catch (e) {}
    }("ACCOUNT NAME"));
</script>

Checkout Events

In order to successfully fire checkout events with the Narrativ Brand Tag, the following code snippet must be populated with information about the checkout, along with a few details about each of the products purchased. This snippet should be placed on your site’s Order Confirmation Page, or the page displayed to customers immediately after they’ve successfully purchased their items.

Make the Checkout Event Code Work for You

Follow the sample code below, making these changes:

Statement

Requirement

Data Type

Notes

var purchased = <dataLayerProducts>;

Replace <dataLayerProducts> with the list of purchased products in your data layer. Each item in this array represents attributes of a single purchased product (explained in the following items).

Object

product_id: purchased[i].<ItemID>,

Replace <ItemID> with the variable name your data layer uses to define item ID, or the unique identifier for the purchased product. This can likely be found in the dataLayerProducts array described above.

String

product_name: purchased[i].<ItemName>,

Replace <ItemName> with the variable name your data layer uses to define item name, or the name for the purchased product. This can likely be found in the dataLayerProducts array described above.

String

product_price: purchased[i].<ItemPrice>,

Replace <ItemPrice> with the variable name your data layer uses to define item price, or the per-unit price of the purchased product. This can likely be found in the dataLayerProducts array described above.

String

Both cart level and product level coupon codes should be captured in this variable (e.g. if a coupon code variable in the data layer is not null, apply X% discount to product_price)

product_quantity: purchased[i].<ItemQuantity>,

Replace <ItemQuantity> with the variable name your data layer uses to define item quantity, or the quantity of the purchased product. This can likely be found in the dataLayerProducts array described above.

Integer

product_brand: purchased[i].<ItemBrand>,

Replace <ItemBrand> with the variable name your data layer uses to define item brand, or the brand of the purchased product. This can likely be found in the dataLayerProducts array described above.

String

If Item Brand is not available, replace <ItemBrand> with null

product_size: purchased[i].<ItemSize>,

Replace <ItemSize> with the variable name your data layer uses to define item size, or the size of the purchased product. This can likely be found in the dataLayerProducts array described above.

String

If Item Size is not available, replace <ItemSize> with null

product_color: purchased[i].<ItemColor>,

Replace <ItemColor> with the variable name your data layer uses to define item color, or the color of the purchased product. This can likely be found in the dataLayerProducts array described above.

String

If Item Color is not available, replace <ItemColor> with null

orderTotal += (purchased[i].<ItemPrice> * purchased[i].<ItemQuantity>);

Replace <ItemPrice> and <ItemQuantity> with the same respective values used above.

String

is_new_customer: <isNewCustomer>,

Replace <isNewCustomer> with a boolean (true/false) indicating if Order is First Order

Boolean

If field is not available, replace <isNewCustomer> with null.

order_id: <OrderID>,

Replace <OrderID> with the order ID, a unique identifier for the order.

String

currency: <CurrencyCode>,

Replace <CurrencyCode> with the three digit currency code that order was placed in (ex: ‘USD’). Uses ISO 4217

String

Note: Remember to also replace ACCOUNT NAME with your Narrativ account name.

<script type="text/javascript">
    var purchased = <dataLayerProducts>;
    var productsPurchased = [];
    var orderTotal = 0;
    for (var i = 0; i < purchased.length; i++) {
      productsPurchased.push({
        product_id: purchased[i].<ItemID>,
        product_name: purchased[i].<ItemName>,
        product_brand: purchased[i].<ItemBrand>,
        product_size: purchased[i].<ItemSize>,
        product_color: purchased[i].<ItemColor>,
        product_price: purchased[i].<ItemPrice>,
        product_quantity: purchased[i].<ItemQuantity>,
      });
      orderTotal += (purchased[i].<ItemPrice> * purchased[i].<ItemQuantity>);
    }

    window.BAMX_EVENT_DATA = {
        page_type: 'checkout',
        is_new_customer: <isNewCustomer>,
        products_purchased: productsPurchased,
        order_id: <OrderID>,
        order_value: orderTotal,
        currency: <CurrencyCode>,
    };

    (function(account) {
        try {
          var b = document.createElement("script");
          b.type = "text/javascript";
          b.src = "https://static.narrativ.com/tags/" + account + ".js";
          b.async = true;
          var a = document.getElementsByTagName("script")[0];
          a.parentNode.insertBefore(b, a);
        } catch (e) {}
    }("ACCOUNT NAME"));
</script>

Shopify Checkout Code

Please use the script tag below in place of the previous checkout code if you prefer to implement through an existing Shopify integration:

<script type="text/javascript">
    if(Shopify.Checkout.step == ‘thank_you’){
        var productsPurchased = [
            {% for line_item in checkout.line_items %}
            {% if line_item.price > 0 %}
            {
                “product_id” : “{{ line_item.product_id }}”,
                “product_name” : “{{ line_item.product_title | capitalize }} {% if
                line_item.product.metafields.c_f.tagline %}
                {{ line_item.product_metafields.c_f.tagline }}{% endif %}”,
                    "product_brand":"{{ line_item.product.vendor }}",
                    "product_size":"{{ line_item.variant.option1 }}",
                    "product_price" : "{{ line_item.price | money_without_currency }}",
                    "product_quantity" : "{{ line_item.quantity }}", },
            {% endif %}
        {% endfor %} ];

    window.BAMX_EVENT_DATA = {
        "page_type": “checkout”,
        "order_id": Shopify.checkout.order_id.toString() || "{{order_number}}",
        "products_purchased": productsPurchased,
        "order_value": Shopify.checkout.subtotal_price || "{{subtotal_price | money_without_currency }}",
        "currency": Shopify.checkout.currency || "{{currency.iso_code}}",
    };

    (function(account) {
        try {
          var b = document.createElement("script");
          b.type = "text/javascript";
          b.src = "https://static.narrativ.com/tags/" + account + ".js";
          b.async = true;
          var a = document.getElementsByTagName("script")[0];
          a.parentNode.insertBefore(b, a);
        } catch (e) {}
    }("ACCOUNT NAME"));
</script>

Note: Remember to also replace ACCOUNT NAME with your Narrativ account name.

Google Tag Manager Implementation

Implementing the Narrativ Brand Tag with Google Tag Manager is a simple process. Follow the instructions below to implement the tag using a “Custom HTML” tag in GTM.

Page Impression Events

Start by navigating to your Google Tag Manager Dashboard.

  • Select the “Tags” menu item from the menu on the left-hand side of the page.

  • Once on the “Tags” page, select the “New” button to create a new tag.

  • Select the “Tag Configuration” box to begin making a new tag.

_images/1_tap_configuration.png

  • Select the “Custom HTML” option to open an empty text field.

_images/2_choose_custom_html.png

  • Copy and paste the code outlined in the above section entitled “Page Impression Events: Implementation”. Make sure you replace ACCOUNT NAME with your Narrativ account name.

_images/3_enter_tag_html.png

  • Select “All Pages” as the correct trigger for these events.

_images/4_select_trigger.png

  • Name the tag “Narrativ Page Impression Events” and double check that the trigger is set to “All Pages”.

_images/5_final_product.png

Checkout Events

  • For checkout events, create a new tag and open the empty text field again.

_images/checkout_1_open_editor.png

  • Follow the instructions outlined in the “Checkout Events: Implementation” Section above to successfully fire checkout events.

Note: var purchased should be set to the data layer variable corresponding to products purchased at checkout. This can be defined independent of GTM variables (see previous screenshot), or it can be found in the Variables section of your Tag Manager dashboard GTM variables referenced in the checkout tag should be wrapped in doubly curly brackets.

Here is an example of the fully implemented checkout code:

_images/checkout_2_confirm_code_product_info.png

  • Select the box under “Triggering” to add a trigger for this tag.

_images/checkout_3_add_trigger.png

  • If you don’t already have a trigger for checkout pages, then it’s easy to create one!

_images/checkout_4_add_confirmation_page_trigger.png

  • The below example has a series of triggers based off of common URL types for checkout or confirmation pages. (E.g. narrativ.com/checkout/ will trigger the “Checkout Page” option). Replace “checkout” with whatever word your site uses on checkout pages. Remember, you only need one trigger!

_images/checkout_4.1_add_confirmation_rules.png

  • Double check the tag name, make sure you’ve updated the code with the information on your checkout page, and make sure you’ve selected the correct trigger.

_images/checkout_5_double_check.png

Publishing Tags

  • Make sure that the tag(s) are showing up in the “Tag” tab.

_images/submit_1_tag_confirmation.png

  • Preview the changes made and fix any errors that pop up in the window.

_images/submit_2_review.png

  • Click the “Submit” button to save your changes (this step is not final)

_images/submit_3_submit_changes.png

  • Double check that everything you modified is in this submission. Name the submission something like “Adding Narrativ Brand Tag” so that it’s easy to find if you need to go back and debug any issues in the future.

_images/submit_4_title_the_changes.png

If you have any issues during this process then reach out to your Narrativ growth manager or email us at solutions@narrativ.com.

Testing the Brand Tag

Page Impressions

To test the page impression code, filter “bam” in Developer Tools and check for these three events on refresh:

_images/test_page_impression.png

Checkouts

Place a test order to QA the checkout tag. Similar to the page impression test, be sure to have “bam” filtered in Developer Tools before you place the order. On the confirmation page, you should see an additional checkout event firing:

_images/test_checkouts.png

When you navigate into the “Request Payload” within the checkout event, you should see information about the order and products purchased:

_images/test_checkouts_payload.png

Please note: We recommend placing an additional test order with a coupon code to ensure order value and product price variables accurately capture any discounts.

If you have any issues during the implementation or testing process, please reach out to your Narrativ growth manager or email us at solutions@narrativ.com.

Custom Publisher Tags

Getting Started

The fastest way to get started on the Narrativ platform is to use our provided Javascript tag. Our publisher tag automatically finds the SmartLinks on your page, updates their destination URLs, and tracks user interaction with them. However, if you have a special use case not covered by our default tag, it is possible to write your own custom integration with our APIs.

Page Session Tracking

To provide the most accurate performance data on your SmartLinks, Narrativ tracks page session events on your website. These events are grouped by a randomly-generated unique identifier called the Page Session UUID. This identifier is a UUID v4, which looks something like:

8132ac19-109a-466e-8037-540a9bd12798

Your tag will need to generate a new Page Session UUID each time a reader lands on a different page/article. Include this value where indicated when submitting events on your page. Do not reuse Page Session UUIDs across different pages or different users.

Note

If you have a single-page application (SPA), generating a new Page Session UUID on Javascript load may not be enough! Ensure that your UUID changes every time the reader navigates to a new article.

Page Impression Events

After generating your Page Session UUID, record the beginning of the page session by firing a Page Impression via the Events API. For example:

POST /api/v1/events/impressions/page_impression/

{
  "organization_type": "publisher",
  "organization_id": 1,
  "user": {
    "page_session_uuid": "8132ac19-109a-466e-8037-540a9bd12798"
  },
  "events": [
    {}
  ]
}

Auctions

For each distinct Auction ID on your page, submit an Auction API request to obtain the new destination URL. For example:

GET https://api.bam-x.com/api/v1/auction/
        ?a=1522995078114976993
        &t=1517261651
        &uuid=8132ac19-109a-466e-8037-540a9bd12798

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "auction_result": {
        "id": "1629147433127336253",
        "auction_id": "1522995078114976993",
        "redirect_url": "https://api.bam-x.com/api/v1/redirect/?a=1522995078114976993&uid_bam=1629147432580451822&ar=1629147433127336253&url=http%3A%2F%2Fwww.shopbop.com.example%2Fkarda-lace-bootie-iro%2Fvp%2Fv%3D1%2F1533877648.htm%3Fsite_refer%3Dbam%26utm_source%3Dbam%26utm_medium%3Dcpc%26utm_campaign%3Dbam%2Bpremium%2Beditorial%26&uuid=8132ac19-109a-466e-8037-540a9bd12798"
      }
    }
  ]
}

Then, replace the href of your link with the new URL. So, an original link that looks like this:

<a href="https://shop-links.co/1522995078114976993" target="_blank">Shop Now</a>

will become:

<a href="https://api.bam-x.com/api/v1/redirect/?a=1522995078114976993&uid_bam=1629147432580451822&ar=1629147433127336253&url=http%3A%2F%2Fwww.shopbop.com.example%2Fkarda-lace-bootie-iro%2Fvp%2Fv%3D1%2F1533877648.htm%3Fsite_refer%3Dbam%26utm_source%3Dbam%26utm_medium%3Dcpc%26utm_campaign%3Dbam%2Bpremium%2Beditorial%26&uuid=8132ac19-109a-466e-8037-540a9bd12798" target="_blank">Shop Now</a>

Sometimes the same SmartLink appears multiple times in a single article. For instance, you may have a clickable slideshow image and some caption text for the same featured product in your story. In this case, your tag should only submit one Auction API request and update both links to the same destination URL.

Third-Party Event Trackers

Some of our retail partners request us to fire their event trackers each time their product links appear on a publisher page. These trackers provide additional insights on your SmartLink performance and help us further optimize your revenue. Auction API responses will list the third-party impression trackers and viewable impression trackers that apply to your SmartLink. For example:

GET https://api.bam-x.com/api/v1/auction/
        ?a=1522995078114976993
        &t=1517261651
        &uuid=8132ac19-109a-466e-8037-540a9bd12798

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "impression_pixel_url": "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
      "auction_result": {
        "tracker_urls": {
          "viewable_impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=lv;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?"
          ],
          "impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=li;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?"
          ]
        },
        "id": "1629147433127336253",
        "auction_id": "1522995078114976993",
        "redirect_url": "https://api.bam-x.com/api/v1/redirect/?a=1522995078114976993&uid_bam=1629147432580451822&ar=1629147433127336253&url=http%3A%2F%2Fwww.shopbop.com.example%2Fkarda-lace-bootie-iro%2Fvp%2Fv%3D1%2F1533877648.htm%3Fsite_refer%3Dbam%26utm_source%3Dbam%26utm_medium%3Dcpc%26utm_campaign%3Dbam%2Bpremium%2Beditorial%26&uuid=8132ac19-109a-466e-8037-540a9bd12798"
      }
    }
  ]
}

Impression trackers should be fired immediately, while viewable impression trackers should be fired once any occurrence of the SmartLink on the page is scrolled into view.

Tracker URLs may include the template parameter {RAND}, which must be replaced with a randomly-generated number prior to firing the tracker. This parameter is used to prevent HTTP caching of the tracker request and response:

https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;ord={RAND};dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?"

To fire a third-party event tracker, insert a new hidden HTML img tag with the tracker URL as the image source:

<img src="https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?" />

Do NOT fire a third-party event tracker more than once per page for the same event, even if the same SmartLink appears multiple times on that page.

Product and Advertiser Information

When the auction system identifies an advertiser (retailer/merchant) that is eligible to receive the click on a SmartLink, it may return additional contextual information about the advertiser and the product being sold. For example:

GET https://api.bam-x.com/api/v1/auction/
    ?a=1629223267830557131
    &t=1517261651
    &uuid=8132ac19-109a-466e-8037-540a9bd12798

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "auction_result": {
        "id": "1629224701990881693",
        "auction_id": "1629223267830557131",
        "redirect_url": "https://api.bam-x.com/api/v1/redirect/?a=1629223267830557131&uid_bam=1629224701957143181&ar=1629224701990881693&url=https%3A%2F%2Fwww.amazon.com.example%2F&uuid=8132ac19-109a-466e-8037-540a9bd12798",
        "product": {
          "merchant": {
            "url": "https://www.amazon.com/",
            "canonical_host": "amazon.com",
            "id": 2186,
            "name": "Amazon"
          },
          "bamx_product_category_id": 3,
          "name": "Designer Handbag",
          "url": "https://www.amazon.com.example/product/1234",
          "price": "299.99",
          "id": 8030310
        }
      }
    }
  ]
}

Your tag can use this information to dynamically update the text of your article for a better reader experience.

How to Download Narrativ Chrome Extension

Step 1. Navigate to Chrome Web Store

Search Narrativ for Publishers, and click ADD TO CHROME.

_images/1.png

Step 2. Add Extension

Click Add Extension when the confirmation window pops up.

_images/2.png _images/3.png

Step 3. Sign In

The Narrativ extension will appear in the top right corner of Chrome. Click on the icon and sign in with your Narrativ dashboard credentials!*

_images/4.png

*Contact your account manager or support@narrativ.com for your Narrativ dashboard access and credentials.

How to Use Narrativ Chrome Extension

Product Feeds

Ingesting Product Feeds

In order for Narrativ to accurately match publisher recommendation links to a merchant’s product, we require a comprehensive product feed. Depending on your preference, we can either fetch your feed or you can send it to us via HTTP, FTP or SFTP using the specifications detailed below. Feeds sent via FTP or SFTP should be scheduled for daily export.

Formatting

We currently support CSV and XML file formats and zip and gzip compressed files. Please ensure the fields GTIN (or SKU if unavailable), Product URL and Stock Status are included in the file. You can view a sample file here.

Send via FTP

Note: Enable passive and binary modes

Field Name

Value

Host

feeds.bam-x.com

Static IP

52.7.95.122

Port

2221

Username

Will be provided to you

Password

Will be provided to you

Filename

USERNAME-USD-yyyy-mm-dd.csv.zip

Send via SFTP

Please generate and provide us with a public RSA key to register as an authorized key for your users.

Field Name

Value

Host

feeds.bam-x.com

Static IP

52.7.95.122

Port

2223

Username

Will be provided to you

Filename

USERNAME-USD-yyyy-mm-dd.csv.zip

If you have any questions about product feed requirements, please feel free to reach out to solutions@narrativ.com for assistance.

Privacy Policy

The Narrativ Company, Inc. (“Narrativ”) takes your privacy very seriously. This Privacy Policy explains how Narrativ collects, uses, and discloses information, and your choices for managing your information preferences.

What This Policy Covers

This Privacy Policy describes Narrativ’s data practices associated with our website (https://narrativ.com) and Narrativ services (“Services”), and the choices that Narrativ provides in connection with our collection and use of your information. This Privacy Policy is intended for website publisher customers (“Publishers”), website merchant customers (“Merchants”) and individual users of websites and apps. For Publishers and Merchants, this Policy explains how Narrativ may collect, use and disclose information associated with your company and with your company’s websites and apps that use Narrativ Services. For individual website and app users, this Privacy Policy explains how Narrativ may collect, use, and disclose information when you visit our website or when you use any website or app that uses Narrativ Services.

Publishers and Merchants and other clients may also have their own policies that govern how they collect, use, and share data. These policies may differ from Narrativ’s policies described in this Privacy Policy. Please consult the privacy policies of the websites you visit and apps you use to become familiar with their privacy practices and to learn about any choices that these companies may offer with respect to their information practices. In addition, any website containing our Services may contain links to websites or content operated and maintained by third parties, over which we have no control. We encourage you to review the privacy policy of a third-party website before disclosing any information to the website.

Information Collection and Use

Narrativ collects data in a variety of ways - including through the use of log files, pixel tags, cookies, and/or similar technologies. Examples of the types of data that we collect are:

  • Browser information (e.g. URL, browser type, “click through” data)

  • Ad reporting or delivery data (e.g. size/type of ad, ad impressions, location/format of ad, data about interactions with the ad)

  • Device-type information (e.g. screen dimensions, device brand and model)

  • Information about your activities on our website and Services

We may combine information that does not directly identify an individual with data collected from other sources and disclose the combined information to participating publishers, advertisers and ad networks so that they can determine whether to bid on ad inventory and in order to improve the relevance of the advertising presented to users. We also use the information we collect to host, operate, maintain, secure, and further develop and improve our Services, such as to keep track of advertising delivery and to measure the effectiveness of advertising delivered through our Services, and investigate compliance with Narrativ’s policies and terms and conditions. Some of the third parties that we work with may contribute additional data to us directly, which we may combine with our own in order to help us provide a better service. We do not collect any information that could be used to directly identify an individual.

Narrativ does not engage in activities that require parental notice or consent under the Children’s Online Privacy Protection Act (COPPA). If you believe that Narrativ has inadvertently collected information from a child under 13 that is subject to parental notice and consent under COPPA, please contact Narrativ using the contact information below to request deletion of the information.

Cookies and Other Similar Technologies. We use cookies (a small file containing a string of characters that uniquely identifies your Web browser), Web beacons (an electronic file placed within a Web site that monitors usage), pixels, etags, and similar technologies to operate and improve our website and Services, including for interest-based advertising as described below. Some of our Service Providers (defined below) may also use such technologies in connection with the services they perform on our behalf.

Information Sharing

We will disclose contact and billing information to third parties only as described in this Privacy Policy:

  • with your express permission;

  • with our affiliates, which include entities controlling, controlled by, or under common control with Narrativ;

  • where we contract with third parties to provide certain services, such as advertising, analytics, data management services, web hosting, and web development (“Service Providers”). We ask Service Providers to confirm that their privacy and security practices are consistent with ours, we provide our Service Providers with only the information necessary for them to perform the services we request, and Service Providers are prohibited from using such information for purposes other than as specified by Narrativ;

  • in the event that Narrativ is merged, sold, or in the event of a transfer of some or all of our assets (including in bankruptcy), or in the event of another corporate change, we may disclose or transfer information in connection with such transaction; and

  • where we believe it is necessary to protect Narrativ or our users; to enforce our terms or the legal rights of Narrativ or others; or to comply with a request from governmental authorities, legal process, or other legal obligations.

We may also share and disclose other information that we collect, including aggregate information, as we consider necessary to develop and provide our Services, including in the ways described above. The information that we share in this way would not be considered to personally identify an individual.

Narrativ may also be required to disclose information in response to lawful requests by public authorities, including to meet national security or law enforcement requirements.

Interest-Based Advertising and Opting Out

Narrativ adheres to the Digital Advertising Alliance (DAA) Self-Regulatory Principles in the US and to the European Digital Advertising Alliance (EDAA) Principles in the EU and the IAB Europe OBA Framework. We are also a member of the Network Advertising Initiative and adhere to the NAI’s Code of Conduct.

The Narrativ Ad Exchange uses cookies, Web beacons, pixels, etags, and similar technologies to give Publishers the possibility to offer, and Ad Exchange advertisers the ability to show, targeted ads on the device on which you are viewing this policy or a different device. These ads are more likely to be relevant to you because they are based on inferences drawn from location data, web viewing data collected across non-affiliated sites over time, and/or application use data collected across non-affiliated apps over time. This is called “interest-based advertising.” In addition, certain third parties may collect data on the Narrativ website and combine this data with information collected from other websites over time for purposes that include interest-based advertising.

Opting Out for Cookie-Based Services: If you would like to learn more about this type of advertising, or would prefer to opt out of website interest-based advertising enabled by Narrativ’s Ad Exchange, European Union residents may opt-out of this form of advertising by companies participating in the EDAA at www.youronlinechoices.com and all other users may visit www.aboutads.info/choices to opt out of this form of advertising by companies participating in the DAA self-regulatory program. Please note that in order for your opt-out choice to be effective using this tool, you must ensure that your browser is set to accept third-party cookies such as the Narrativ opt-out cookie. Some browsers block third-party cookies by default, and you may need to change your browser settings to accept third-party cookies before opting out.

Opting Out for Certain Non-Cookie Services (in applicable countries): To help identify your browser and/or possible relationships between different browsers and devices, Narrativ or our partners may use the local storage or cache in your browser. Using the browser cache or local storage helps Narrativ or our partners deliver interest-based advertising to a browser without the use of third-party cookies. We are using local storage only for application processing, not for any tracking processes. To opt out of Narrativ’s use of local storage or the browser cache to provide its services, please (1) use any tools provided by your browser to clear local storage and the browser cache, and (2) turn on any “Do Not Track” header setting offered by your browser. As long as the two steps are completed and maintained on a browser, Narrativ will not use local storage or the cache on that browser to identify and sync browsers and devices. If you also want to opt out of Narrativ’s use of third-party cookies for interest-based advertising as enabled by Narrativ’s Ad Exchange, please see instructions above.

Opting Out for Mobile Application Data: To opt out of Narrativ’s collection, use, and transfer of data for interest-based advertising on mobile apps, you may download the DAA’s AppChoices application from the Android or iOS app store on your mobile device. Users outside the United States may not have access to this application; instead, you can use “Limit Ad Tracking” in your iOS settings or “Opt out of interest-based ads” in your Android settings to limit Narrativ’s collection of data for interest-based advertising.

Opting Out for Location Data: You may opt out of our collection, use, and transfer of precise location data by using the location services controls in your mobile device’s settings. Effect of Opting Out: If you use a different device or browser, or erase cookies from your browser, you will need to renew your opt-out choice.

If you opt out of Narrativ’s practices, you may continue to receive interest-based advertising through other companies. Third-party advertisers and ad networks that participate in the Narrativ Ad Exchange may also use their own cookies and other ad service technologies to display and track their ads. We do not control and are not responsible for such third-party advertisers’ and ad networks’ information practices or their use of cookies and other ad service technologies. To learn more about the practices of these companies, please read their privacy policies.

Even if you opt-out, Narrativ may continue to collect data for other purposes and you still will receive advertising from the Narrativ Ad Exchange when you visit websites of a Publisher who uses our Services – but such advertising will not be targeted to you.

Reviewing and Updating Information

Narrativ takes reasonable steps to ensure that information is accurate, complete, current, and reliable for its intended use. For contact or billing information submitted through our website, you may review, correct, update, or change your information, request that we deactivate your account, or remove your information from our direct marketing efforts, at any time by e-mailing us at privacy@narrativ.com.

International Information Transfers

Please be aware that the information we collect, including contact and billing information, may be transferred to and maintained on servers or databases located outside your state, province, country, or other jurisdiction, where the privacy laws may not be as protective as those in your location. If you are located outside of the United States, please be advised that we process and store information in the United States and your consent to this Privacy Policy or use of Narrativ Services represents your agreement to this processing.

Security

Information that we collect is stored using procedures and practices reasonably designed to help protect information from unauthorized access, destruction, use, modification, or disclosure.

Policy Updates

From time to time, we may change this Privacy Policy. If we decide to change this Privacy Policy, in whole or in part, we will inform you by posting the revised Privacy Policy on the Narrativ website. Those changes will go into effect on the effective date disclosed in the revised Privacy Policy.

Contact Us

If you have any questions or concerns regarding this Narrativ Privacy Policy, please contact us by emailing us at privacy@narrativ.com.

Support

Need additional help? Feel free to reach out with any questions on integration or Narrativ’s content marketing platform!