@edx/frontend-plugin-advertisements 1.5.0 → 1.6.0

package/README.rst

@@ -0,0 +1,93 @@
+frontend-plugin-advertisements
+##############################
+
+|license-badge| |status-badge| |ci-badge| |codecov-badge|
+
+.. |license-badge| image:: https://img.shields.io/github/license/edx/frontend-plugin-advertisements.svg
+    :target: https://github.com/edx/frontend-plugin-advertisements/blob/main/LICENSE
+    :alt: License
+
+.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen
+
+.. |ci-badge| image:: https://github.com/edx/frontend-plugin-advertisements/actions/workflows/ci.yml/badge.svg
+    :target: https://github.com/edx/frontend-plugin-advertisements/actions/workflows/ci.yml
+    :alt: Continuous Integration
+
+.. |codecov-badge| image:: https://codecov.io/github/edx/frontend-plugin-advertisements/coverage.svg?branch=main
+    :target: https://codecov.io/github/edx/frontend-plugin-advertisements?branch=main
+    :alt: Codecov
+
+Purpose
+=======
+
+This repository hosts plugin components intended for use in frontend-app-learning plugin slots. These components are related
+to in course advertising and experimentation around in course advertising.
+
+For more on the frontend plugin framework, please see https://github.com/openedx/frontend-plugin-framework/tree/master.
+
+Getting Started
+===============
+
+Devstack Installation
+---------------------
+This plugin is intended for use with the `Learning MFE`_. Please follow instructions for running the Learning MFE as
+documented in the repository README.
+
+.. _Learning MFE: https://github.com/openedx/frontend-app-learning
+
+Development
+-----------
+This plugin is intended for use with the `Learning MFE`_, specifically with several plugin slots defined in the MFE.
+In order to install a local checkout of this plugin into the `Learning MFE`_ instead of from npm, follow the
+documentation for `local module development`_ in the `Learning MFE`_. Additionally, if you would like for these
+components to appear in the correct plugin slots, you will need a local ``env.config.js`` file in your copy of
+``frontend-app-learning``.
+
+If you are planning to run the `Learning MFE`_ in `devstack`_, be sure to clone this repository into a ``src``
+subdirectory of your `devstack`_ workspace directory so that the code is properly mounted into the `Learning MFE`_
+Docker container. You will need to update the ``dir`` key in your ``module.config.js`` file appropriately. See
+the `Mounting frontend packages from src directory`_ ADR in the `devstack`_ repository for further details.
+
+If you want to install a local checkout of this plugin for use in your `Learning MFE`_ ``env.config.jsx`` file,
+follow the documentation mentioned above. However, if you want do active development on this plugin and wish to see your
+changes immediately reflected in the `Learning MFE`_, then you will need to modify your ``module.config.js`` to reference
+the ``src`` directory of this ``repository`` in the ``dist`` key instead of the ``dist`` directory. Below is an example
+``module.config.js`` for this use case. If you set up your ``module.config.js`` this way, your changes will be picked
+up by the `Learning MFE`_ via the hot module reloading process.::
+
+  module.exports = {
+    localModules: [
+        { moduleName: '@edx/frontend-plugin-advertisements', dir: '../src/frontend-plugin-advertisements', dist: 'src' },
+    ],
+  };
+
+.. _devstack: https://github.com/openedx/devstack
+.. _Learning MFE: https://github.com/openedx/frontend-app-learning
+.. _local module development: https://github.com/openedx/frontend-app-learning#local-module-development
+.. _Mounting frontend packages from src directory: https://github.com/openedx/devstack/blob/master/docs/decisions/0005-frontend-package-mounts.rst
+
+Development with Optimizely
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This repository uses the Optimizely SDK to implement frontend experiments. In order to simplify local development,
+this repository contains a mock Optimizely implementation. Please see the `instructions`_ for further details.
+
+.. _instructions: https://github.com/edx/frontend-plugin-advertisements/tree/main/src/mocks/optimizely/README.rst
+
+License
+=======
+
+The code in this repository is licensed under the AGPLv3 unless otherwise
+noted.
+
+Please see `LICENSE <LICENSE>`_ for details.
+
+
+People
+======
+
+Contact `edx/masters-devs-cosmonauts` if you need help with this repository.
+
+Reporting Security Issues
+=========================
+
+Please do not report security issues in public.  Email security@edx.org instead.

package/dist/mocks/optimizely/README.rst

@@ -0,0 +1,46 @@
+Optimizely Mock Implementation
+##############################
+
+Purpose
+=======
+
+This repository uses the `Optimizely SDK`_ to implement frontend experiments. Using Optimizely requires the use of an
+SDK key or datafile. This poses a problem for development locally, because it requires that an `Optimizely environment`_
+exists for local environments. When developing locally, it may be preferable not to rely explicitly on Optimizely and
+to reserve testing the Optimizely flow in a staging environment.
+
+This module contains a mock Optimizely implementation module that allows engineers to hardcode the return
+values of the functions of the `Optimizely SDK`_, namely the `useDecision hook`_. 
+
+Usage
+=====
+
+The implementations of the `createInstance function`_ and the `OptimizelyProvider component`_ are no-op pass through
+functions. They do not do anything.
+
+In order to modify the experiment and how your user is bucketed, you will need to modify the `useDecision hook`_
+implementation. Use the React SDK documentation to determine how to modify this function to suit your needs.
+
+In addition, you will need to update your ``module.config.js`` file in your local checkout of the Learning MFE to
+map the ``@optimizely/react-sdk`` module to this mock module.
+
+A sample ``module.config.js`` file is shown below, but please refer to the documentation for `local module development`_
+in the `Learning MFE`_ for more information.
+
+
+.. code-block::
+
+    module.exports = {
+        localModules: [
+            { moduleName: '@edx/frontend-plugin-advertisements', dir: '../src/frontend-plugin-advertisements', dist: 'src' },
+            { moduleName: '@optimizely/react-sdk', dir: '../src/frontend-plugin-advertisements/src/mocks/optimizely', dist: '.' },
+        ],
+    };
+
+.. _createInstance function: https://docs.developers.optimizely.com/feature-experimentation/docs/initialize-sdk-react
+.. _Learning MFE: https://github.com/openedx/frontend-app-learning
+.. _local module development: https://github.com/openedx/frontend-app-learning#local-module-development
+.. _Optimizely environment: https://docs.developers.optimizely.com/feature-experimentation/docs/manage-environments
+.. _OptimizelyProvider component: https://docs.developers.optimizely.com/feature-experimentation/docs/optimizelyprovider
+.. _Optimizely SDK: https://docs.developers.optimizely.com/feature-experimentation/docs/javascript-react-sdk
+.. _useDecision hook: https://docs.developers.optimizely.com/feature-experimentation/docs/usedecision-react

package/dist/mocks/optimizely/index.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useDecision = exports.createInstance = exports.OptimizelyProvider = void 0;
+/* eslint-disable no-unused-vars */
+/* eslint-disable react/prop-types */
+
+const useDecision = experimentKey => [{
+  enabled: false,
+  variationKey: 'fill me in'
+}];
+exports.useDecision = useDecision;
+const OptimizelyProvider = _ref => {
+  let {
+    optimizely,
+    user,
+    children = null
+  } = _ref;
+  return children;
+};
+exports.OptimizelyProvider = OptimizelyProvider;
+const createInstance = args => null;
+exports.createInstance = createInstance;
+//# sourceMappingURL=index.js.map

package/dist/mocks/optimizely/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["useDecision","experimentKey","enabled","variationKey","exports","OptimizelyProvider","_ref","optimizely","user","children","createInstance","args"],"sources":["../../../src/mocks/optimizely/index.jsx"],"sourcesContent":["/* eslint-disable no-unused-vars */\n/* eslint-disable react/prop-types */\n\nconst useDecision = (experimentKey) => (\n  [{ enabled: false, variationKey: 'fill me in' }]\n);\n\nconst OptimizelyProvider = ({ optimizely, user, children = null }) => children;\n\nconst createInstance = (args) => (null);\n\nexport { createInstance, useDecision, OptimizelyProvider };\n"],"mappings":";;;;;;AAAA;AACA;;AAEA,MAAMA,WAAW,GAAIC,aAAa,IAChC,CAAC;EAAEC,OAAO,EAAE,KAAK;EAAEC,YAAY,EAAE;AAAa,CAAC,CAChD;AAACC,OAAA,CAAAJ,WAAA,GAAAA,WAAA;AAEF,MAAMK,kBAAkB,GAAGC,IAAA;EAAA,IAAC;IAAEC,UAAU;IAAEC,IAAI;IAAEC,QAAQ,GAAG;EAAK,CAAC,GAAAH,IAAA;EAAA,OAAKG,QAAQ;AAAA;AAACL,OAAA,CAAAC,kBAAA,GAAAA,kBAAA;AAE/E,MAAMK,cAAc,GAAIC,IAAI,IAAM,IAAK;AAACP,OAAA,CAAAM,cAAA,GAAAA,cAAA","ignoreList":[]}

package/dist/mocks/optimizely/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "optimizely",
+  "version": "1.0.0",
+  "description": "Optimizely mock application for local development",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "edX",
+  "license": "AGPL-3.0"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edx/frontend-plugin-advertisements",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Frontend plugin for edX in course advertisements",
   "repository": {
     "type": "git",