@mindful-web/marko-web-native-x 1.0.0

package/.eslintignore

@@ -0,0 +1 @@
+*.marko.js

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Parameter1 LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# Mindful Web Marko Web NativeX Components
+NativeX components for Mindful Web/Marko websites.
+
+## Configuration
+
+All NativeX components rely upon an instance of the [NativeXConfiguration](config.js) class being provided. For ease of use, this configuration is typically set into the Express app locals via the [start-server](../marko-web/start-server.js) utility, but must be provided when querying for an advertisement or a story. This configuration defines (at minimum) the NativeX instance URI and the default template alias. If website section-based templates are in use, they must be defined after creation:
+```js
+const NativeXConfiguration = require('@mindful-web/marko-web-native-x/config');
+
+const config = new NativeXConfiguration('https://example.native-x.parameter1.com',
+  {
+    enabled: true,
+    defaultAlias: 'default',
+  }
+);
+
+// Configure a placement
+config.setPlacement({
+  alias: 'default',
+  name: 'default',
+  id: '5d4b04769f69b200013ab109',
+});
+
+// Configure multiple placements for an alias
+config.setAliasPlacements('my-custom-alias', [
+  { name: 'custom-placement-1', id: '95d4b04769f69b200013ab10' },
+  { name: 'custom-placement-2', id: '095d4b04769f69b200013ab1' },
+]);
+
+module.exports = config;
+```
+
+## Usage
+
+### Advertisements
+
+Rendering NativeX advertisements is typically done by using the `<marko-web-native-x-render>` component. If NativeX is enabled, this component then uses the `<marko-web-native-x-retrieve>` component to query NativeX for an advertisement. When an advertisement is available, the content node will be replaced by the ad details.
+
+The render component requires the following properties:
+- `config`: An instance of the NativeXConfiguration class.
+- `name`: The name of the placement to use (as defined by `setPlacement` and `setAliasPlacements`)
+- `aliases`: An array of active aliases to use. (See aliases below)
+- `node`: The content node that may become a NativeX ad.
+- `when`: A boolean. When truthy, the content node will be replaced by the ad (if available)
+- `sectionName`: Used by the conversion utilities. Because ads do not have website context, indicate the name of the primary section of the "content" (the ad, once replaced)
+
+#### Aliases
+
+When registering an placement, you must specify an alias. If you are not using any alias-aware placements, you should use the value `default` for the alias field. This is the most common!
+
+In an atypical website deployment, multiple NativeX placements may be used to further segment NativeX metrics. When a placement is requested, the supplied aliases are checked against registered placements. If a more specific placement exists, it is used preferentially over the `default` placement with a matching `name`.
+
+For example, consider the following:
+```js
+const config = new NativeXConfiguration(...);
+
+// The default placement
+config.setPlacement({ alias: 'default', name: 'default', id: '5d4b04769f69b200013ab109' });
+config.setPlacement({ alias: 'section-1', name: 'default', id: '95d4b04769f69b200013ab10' });
+config.setPlacement({ alias: 'section-2', name: 'default', id: '095d4b04769f69b200013ab1' });
+
+const aliases = ['section-1/child-section/grand-child', 'section-1/child-section', 'section-1'];
+
+const placement = config.getPlacement({ name: 'default', aliases });
+console.log(placement.id);
+// 95d4b04769f69b200013ab10
+```
+
+
+### Stories
+
+To render a NativeX story in a consuming application, import the `with-story` middleware. This middleware requires a NativeX configuration and a Marko template to render a response. It also supports sending a custom `queryFragment` to return additional fields, if needed.
+
+An Express route
+```js
+// my-site/routes/native-x-story.js
+const withNativeXStory = require('@mindful-web/marko-web-native-x/middleware/with-story.js');
+const config = require('../config/native-x');
+const template = require('../templates/native-x-story');
+
+module.exports = (app) => {
+  app.use('/some-path/:id', withNativeXStory({
+    config,         // Required. An instance of the NativeXConfiguration class.
+    template,       // Required. A Marko template used to render the story.
+    queryFragment,  // Optional. A GraphQL query fragment specifying included fields.
+  }));
+};
+```
+
+A minimal Marko template
+```marko
+<!-- my-site/templates/native-x-story.marko -->
+$ const { document } = out.global;
+$ const { story } = input;
+
+<${document}>
+  <@container>
+    <@page>
+      <if(imgSrc)>
+        <marko-web-img class="img-fluid" src=story.primaryImage.src />
+      </if>
+      <h1>${story.title}</h1>
+      <if(story.teaser)>
+        <p>${story.teaser}</p>
+      </if>
+      <hr>
+      $!{story.body}
+    </@page>
+  </@container>
+</>
+```
+
+A GraphQL fragment definition
+```js
+// my-site/graphql/fragments/story.js
+
+const gql = require('graphql-tag');
+
+module.exports = gql`
+  fragment MyCustomStoryFragment on Story {
+    id
+    title
+    campaigns {
+      totalCount
+      edges {
+        id
+        name
+      }
+    }
+  }
+`;
+
+```
+#### Event Tracking and analytics
+
+To utilize NativeX's story analytics, you must use the event tracking [utility functions](utils/gtm-events) to send events to the NativeX GTM container.
+
+The GTM container can be initialized by including the `<marko-web-native-x-gtm-init>` component within your `document`'s `<head>`:
+```marko
+<${document}>
+  <@head>
+    <marko-web-native-x-gtm-init />
+  </@head>
+</>
+```
+Before sending any events, make sure to include the `<marko-web-native-x-story-track-init>` component. This component initializes the data layer with the story data that other events rely upon.
+```marko
+<${document}>
+  <@head>
+    <marko-web-native-x-gtm-init />
+  </@head>
+  <@page>
+    <marko-web-native-x-story-track-init story=story />
+  </@page>
+</>
+```
+
+See examples of available events below. By default, including the `<marko-web-native-x-story-track-page-view>` component will populate the datalayer with the story details. To disable this behavior, send the `push=false` parameter when including the component. All other story components assume this has already happened -- to force population of the data layer, send the `push=true` parameter when including the relevant component.
+
+##### Page View
+To send a page view, include the `<marko-web-native-x-story-track-page-view>` and pass the `story` property through (from the Nx middleware):
+```marko
+$ const { story } = input;
+
+<${document}>
+  <@head>
+    <marko-web-native-x-gtm-init />
+  </@head>
+  <@page>
+    <marko-web-native-x-story-track-page-view />
+    <h1>${story.title}</h1>
+  </@page>
+</>
+```
+
+##### Outbound Links
+To automatically track outbound links, include the `<marko-web-native-x-story-track-outbound-links>` component. This component requires a DOM selector in order to limit the tracking to a subset of links:
+```marko
+$ const { story } = input;
+
+<${document}>
+  <@head>
+    <marko-web-native-x-gtm-init />
+  </@head>
+  <@page>
+    <h1>${story.title}</h1>
+    <div id="my-story-body">
+      <a href="https://google.com">This will be tracked when clicked!</a>
+    </div>
+    <marko-web-native-x-story-track-outbound-links container="#my-story-body" />
+  </@page>
+</>
+```
+
+##### Social Sharing
+If using the [marko-web-social-sharing](../marko-web-social-sharing) package, you can automatically track any share attempts by including the `<marko-web-native-x-story-track-social-share>` component in your story template:
+```marko
+$ const { story } = input;
+
+<${document}>
+  <@head>
+    <marko-web-native-x-gtm-init />
+  </@head>
+  <@page>
+    <marko-web-native-x-story-track-social-share />
+    <h1>${story.title}</h1>
+    <marko-web-social-sharing path=story.url providers=["facebook", "email"] />
+  </@page>
+</>
+```
+
+##### End of content
+To automatically track when the user reaches the bottom of the page, include the `<marko-web-native-x-story-track-end-of-content>` component below your story. This event will fire when the element comes into view:
+```marko
+$ const { story } = input;
+
+<${document}>
+  <@head>
+    <marko-web-native-x-gtm-init />
+  </@head>
+  <@page>
+    <h1>${story.title}</h1>
+    <p>...</p>
+    <p>...</p>
+    <p>...</p>
+    <marko-web-native-x-story-track-end-of-content />
+  </@page>
+</>
+```
+
+##### Manual/advanced implementations
+You can also send an event directly by using one of the available utility functions:
+```vue
+<script>
+import { endOfContent } from "@mindful-web/marko-web-native-x/utils/gtm-events";
+
+export default {
+  created() {
+    endOfContent();
+  }
+};
+</script>
+```

package/apollo/create-client.js

@@ -0,0 +1,42 @@
+const fetch = require('node-fetch');
+const { get } = require('@mindful-web/object-path');
+
+const getOperationName = (string) => {
+  const matches = /query\s+([a-z0-9]+)[(]?.+{/gi.exec(string);
+  if (matches && matches[1]) return matches[1];
+  return undefined;
+};
+
+module.exports = (uri) => Object.create({
+  query: async ({ query, variables, headers }) => {
+    const body = JSON.stringify({
+      operationName: getOperationName(query),
+      variables,
+      query: get(query, 'loc.source.body', query),
+    });
+
+    const res = await fetch(uri, {
+      method: 'POST',
+      headers: {
+        ...headers,
+        'content-type': 'application/json',
+      },
+      body,
+    });
+    const json = await res.json();
+    if (!res.ok || (json && json.errors)) {
+      if (!json || !json.errors) {
+        const err = new Error(`An unknown, fatal GraphQL error was encountered (${res.status})`);
+        err.statusCode = res.status;
+        throw err;
+      }
+      const [networkError] = json.errors;
+      const err = new Error(networkError.message);
+      const { extensions } = networkError;
+      if (extensions) err.code = extensions.code;
+      if (extensions && extensions.exception) err.statusCode = extensions.exception.statusCode;
+      throw err;
+    }
+    return json;
+  },
+});

package/apollo/graphql/fragments/image.js

@@ -0,0 +1,12 @@
+const gql = require('graphql-tag');
+
+module.exports = gql`
+  fragment ImageFragment on Image {
+    id
+    src
+    focalPoint {
+      x
+      y
+    }
+  }
+`;

package/apollo/graphql/fragments/publisher-stories.js

@@ -0,0 +1,20 @@
+const gql = require('graphql-tag');
+const imageFragment = require('./image');
+
+module.exports = gql`
+  fragment DefaultPublishedStoriesFragment on Story {
+    id
+    title
+    teaser
+    url
+    publishedAt
+    primaryImage {
+      ...ImageFragment
+    }
+    advertiser {
+      id
+      name
+    }
+  }
+  ${imageFragment}
+`;

package/apollo/graphql/fragments/related-stories.js

@@ -0,0 +1,20 @@
+const gql = require('graphql-tag');
+const imageFragment = require('./image');
+
+module.exports = gql`
+  fragment DefaultRelatedStoryFragment on Story {
+    id
+    title
+    teaser
+    url
+    publishedAt
+    primaryImage {
+      ...ImageFragment
+    }
+    advertiser {
+      id
+      name
+    }
+  }
+  ${imageFragment}
+`;

package/apollo/graphql/fragments/story.js

@@ -0,0 +1,24 @@
+const gql = require('graphql-tag');
+const imageFragment = require('./image');
+
+module.exports = gql`
+  fragment DefaultStoryFragment on Story {
+    id
+    title
+    teaser
+    body
+    url
+    publishedAt
+    primaryImage {
+      ...ImageFragment
+    }
+    advertiser {
+      id
+      name
+      logo {
+        ...ImageFragment
+      }
+    }
+  }
+  ${imageFragment}
+`;

package/apollo/graphql/queries/publisher-stories.js

@@ -0,0 +1,19 @@
+const { extractFragmentData } = require('@mindful-web/web-common/utils');
+const gql = require('graphql-tag');
+
+module.exports = (queryFragment) => {
+  const { spreadFragmentName, processedFragment } = extractFragmentData(queryFragment);
+  return gql`
+    query MarkoWebPublisherStories($input: PublisherStoriesInput!, $pagination: PaginationInput, $sort: StorySortInput) {
+      publisherStories(input: $input, pagination: $pagination, sort: $sort) {
+        edges {
+          node {
+            id
+            ${spreadFragmentName}
+          }
+        }
+      }
+    }
+    ${processedFragment}
+  `;
+};

package/apollo/graphql/queries/related-stories.js

@@ -0,0 +1,19 @@
+const { extractFragmentData } = require('@mindful-web/web-common/utils');
+const gql = require('graphql-tag');
+
+module.exports = (queryFragment) => {
+  const { spreadFragmentName, processedFragment } = extractFragmentData(queryFragment);
+  return gql`
+    query MarkoWebRelatedAdvertiserStories($input: AdvertiserStoriesInput!) {
+      advertiserStories(input: $input) {
+        edges {
+          node {
+            id
+            ${spreadFragmentName}
+          }
+        }
+      }
+    }
+    ${processedFragment}
+  `;
+};

package/apollo/graphql/queries/story.js

@@ -0,0 +1,15 @@
+const { extractFragmentData } = require('@mindful-web/web-common/utils');
+const gql = require('graphql-tag');
+
+module.exports = (queryFragment) => {
+  const { spreadFragmentName, processedFragment } = extractFragmentData(queryFragment);
+  return gql`
+    query MarkoWebStoryPage($input: PublishedStoryInput!) {
+      publishedStory(input: $input) {
+        id
+        ${spreadFragmentName}
+      }
+    }
+    ${processedFragment}
+  `;
+};

package/browser/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('../../../eslintrc.browser');

package/browser/index.js

@@ -0,0 +1,10 @@
+const NativeXTrackEndOfContent = () => import(/* webpackChunkName: "native-x-track-end-of-content" */ './track-end-of-content.vue');
+const NativeXTrackSocialShare = () => import(/* webpackChunkName: "native-x-track-social-share" */ './track-social-share.vue');
+const NativeXTrackOutboundLinks = () => import(/* webpackChunkName: "native-x-track-outbound-links" */ './track-outbound-links.vue');
+
+export default (Browser) => {
+  const { EventBus } = Browser;
+  Browser.register('NativeXTrackEndOfContent', NativeXTrackEndOfContent);
+  Browser.register('NativeXTrackSocialShare', NativeXTrackSocialShare, { provide: { EventBus } });
+  Browser.register('NativeXTrackOutboundLinks', NativeXTrackOutboundLinks);
+};

package/browser/track-end-of-content.vue

@@ -0,0 +1,20 @@
+<template>
+  <div id="native-x-end-of-content" />
+</template>
+
+<script>
+import { endOfContent } from '../utils/gtm-events';
+
+export default {
+  created() {
+    this.observer = new IntersectionObserver((event) => {
+      if (event[0].isIntersecting) {
+        endOfContent();
+      }
+    });
+  },
+  mounted() {
+    this.observer.observe(this.$el);
+  },
+};
+</script>

package/browser/track-outbound-links.vue

@@ -0,0 +1,26 @@
+<template>
+  <div />
+</template>
+
+<script>
+import { outboundLink } from '../utils/gtm-events';
+
+export default {
+  props: {
+    container: {
+      type: String,
+      required: true,
+    },
+  },
+  created() {
+    const elements = document.querySelectorAll(`${this.container} a[href]`);
+    elements.forEach((element) => {
+      const url = element.getAttribute('href');
+      element.addEventListener('click', (e) => {
+        e.preventDefault();
+        outboundLink(url);
+      });
+    });
+  },
+};
+</script>

package/browser/track-social-share.vue

@@ -0,0 +1,23 @@
+<template>
+  <div />
+</template>
+
+<script>
+import { share } from '../utils/gtm-events';
+
+export default {
+  inject: ['EventBus'],
+  props: {
+    eventName: {
+      type: String,
+      default: 'social-share-open',
+    },
+  },
+  created() {
+    this.EventBus.$on(this.eventName, (event) => {
+      const provider = event && event.provider && event.provider.name ? event.provider.name : null;
+      if (provider) share(provider);
+    });
+  },
+};
+</script>

package/components/fetch-elements.marko

@@ -0,0 +1,21 @@
+import { warn } from "@mindful-web/utils";
+import fetchElements from "../services/fetch-elements";
+
+$ const { req } = out.global;
+
+$ const { uri, id, opts } = input;
+$ const args = {
+  uri,
+  placementId: id,
+  opts,
+  req,
+};
+
+<if(uri && id)>
+  <marko-web-resolve|{ resolved }| promise=fetchElements(args)>
+    <${input.renderBody} ads=resolved.ads />
+  </marko-web-resolve>
+</if>
+<else>
+  $ warn('Unable to fetch elements from NativeX: a uri and placement ID are required.');
+</else>

package/components/fetch-elements.marko.js

@@ -0,0 +1,58 @@
+// Compiled using marko@4.20.2 - DO NOT EDIT
+"use strict";
+
+var marko_template = module.exports = require("marko/dist/html").t(__filename),
+    marko_componentType = "/@mindful-web/marko-web-native-x$1.0.0/components/fetch-elements.marko",
+    marko_component = require("./fetch-elements.marko"),
+    marko_renderer = require("marko/dist/runtime/components/renderer"),
+    module_utils_module = require("@mindful-web/utils"),
+    utils_module = module_utils_module.default || module_utils_module,
+    warn = module_utils_module.warn,
+    module_fetchElements = require("../services/fetch-elements"),
+    fetchElements = module_fetchElements.default || module_fetchElements,
+    marko_dynamicTag = require("marko/dist/runtime/helpers/dynamic-tag"),
+    marko_web_resolve_template = require("@mindful-web/marko-core/components/resolve.marko"),
+    marko_loadTag = require("marko/dist/runtime/helpers/load-tag"),
+    marko_web_resolve_tag = marko_loadTag(marko_web_resolve_template);
+
+function render(input, out, __component, component, state) {
+  var data = input;
+
+  const { req } = out.global;
+
+  const { uri, id, opts } = input;
+
+  const args = {
+  uri,
+  placementId: id,
+  opts,
+  req,
+};
+
+  if (uri && id) {
+    marko_web_resolve_tag({
+        promise: fetchElements(args),
+        renderBody: function(out, { resolved }) {
+          marko_dynamicTag(out, input.renderBody, function() {
+            return {
+                ads: resolved.ads
+              };
+          }, null, null, null, __component, "1");
+        }
+      }, out, __component, "0");
+  } else {
+    warn('Unable to fetch elements from NativeX: a uri and placement ID are required.');
+  }
+}
+
+marko_template._ = marko_renderer(render, {
+    e_: marko_componentType
+  }, marko_component);
+
+marko_template.meta = {
+    id: "/@mindful-web/marko-web-native-x$1.0.0/components/fetch-elements.marko",
+    component: "./fetch-elements.marko",
+    tags: [
+      "@mindful-web/marko-core/components/resolve.marko"
+    ]
+  };

package/components/gtm-init.marko

@@ -0,0 +1,21 @@
+import defaultValue from "@mindful-web/marko-core/utils/default-value";
+import { get, getAsObject } from "@mindful-web/object-path";
+
+$ const { req } = out.global;
+$ const story = getAsObject(input, "story");
+$ const on = defaultValue(input.on, "load");
+$ const requestFrame = defaultValue(input.requestFrame, true);
+$ const targetTag = defaultValue(input.targetTag, "body");
+$ const containerId = "GTM-MNQH25L";
+
+<marko-web-gtm-init
+  name="dataLayerNativeX"
+  container-id=containerId
+  on=on
+  request-frame=requestFrame
+  target-tag=targetTag
+  start=true
+  push=input.push
+/>
+
+<marko-web-gtm-noscript container-id=containerId />