donation-encourager v1.2.0

Donation Encourager

Remind your readers with a smile about donating and provide them an easy way to do so. The tool places itself in (or below) the body text of your site's articles. It comes with different levels of intrusiveness, based on the amount of read contents by the user, and gives you a lot of possibilites for customization – check out our example and the API sections below.

The tool was developed by dekoder.org and Palasthotel.

Example

Check out our dekoder-test-page and use the red buttons to see the Donation Encourager in different configurations.

Download

Find the latest build here.

Quick Start

  <script src="donation-encourager.js" defer></script>
  <script>
    window.donEncLayer = window.donEncLayer || [];
    function donEnc() {donEncLayer.push(arguments)};
    donEnc("init", {
      targetSelector: ".ph-article-text",
      ctaTargetUrl: function(amount) { return "https://www.dekoder.org/de/spenden?tw_amount=" + amount; },
    });
    donEnc("pageview");
  </script>

The init action passes a settings object into the app. You have to specify at least two options:

1. targetSelector: Tell the app where to place its boxes (usually the article's body).
2. • ctaTargetUrl: Tell the app which donation URL to open on button click.
   • Alternatively twingleWidgetUrl: If you use Twingle, you can also render your Twingle donation widget inside the donation encourager box.

Actions

You can control the app with actions, which are triggered by the above defined donEnc() function.

donEnc(actionType, actionData);

(Implementation: site-actions.js)

Settings

The settings object has the following properties:

(Implementation: settings-default.js)

Content Types

You can track multiple content types by providing a contentType identifier in your donEnc('pageview', contentType) function. In your settings.contentType object, make sure to provide according namings in singular and plural for each of the used content type identifiers.

const CONTENT_TYPES_DEFAULT = {
  default: { singular: "Inhalt", plural: "Inhalte" },
  article: { singular: "Artikel", plural: "Artikel" },
  gnose: { singular: "Gnose", plural: "Gnosen" }
};

Intrusiveness

The donation encourager allows you to define multiple levels of intrusiveness. These configuration is stored in an array of objects in settings.intrusivenessLevels.

const INTRUSIVENESS_LEVELS_DEFAULT = [
  {
    // level 1
    contentThreshold: 0,
    boxSettings: [{ position: "bottom", expanded: true }],
    itemSelectorSettings: {
      preselectedItemsFilter: (item, i) => i === 0,
    }
  },
  {
    // level 2
    contentThreshold: 5,
    boxSettings: [
      { position: "middle", expanded: false },
      { position: "bottom", expanded: true }
    ],
    itemSelectorSettings: {
      preselectedItemsFilter: (item, i) => i === 1,
    }
  },
  {
    // level 3
    contentThreshold: 10,
    boxSettings: [
      { position: "middle", expanded: true },
      { position: "bottom", expanded: true }
    ],
    itemSelectorSettings: {
      preselectedItemsFilter: (item, i) => i === 2,
    },
    contentLockEnabled: true
  }
];

Each level is defined by an object with the following properties:

ItemSelector items

The ItemSelector uses emoji icons. Defaults:

const ITEMS_DEFAULT = [
  { value: 2, icon: "🍭" },
  { value: 4, icon: "🍺️" },
  { value: 6, icon: "🌹" },
  { value: 16, icon: "🎫" },
];

Strings

The texts for the donation encourager boxes can be defined as static strings or, in case of lead, body, ctaBtn and footer, as functions that use some tracker data and the selected amount from the ItemSelector as arguments. See the defaults for details:

const STRINGS_DEFAULT = {
  currency: (amount) => `${amount} €`,
  and: "und",
  hours: { singular: "Stunde", plural: "Stunden" },
  minutes: { singular: "Minute", plural: "Minuten" },
  lead: (totalContents) =>
    `${totalContents === 1 ? "Inhalt" : "Inhalte"} bisher gelesen`,
  body: (timeStr, contentsStr, amountStr, storage) =>
    storage.totalContents
      ? `Du hast bislang <strong>${contentsStr}</strong> auf dekoder gelesen.* Was ${
          storage.totalContents === 1
            ? storage.readContents.gnose === 1
              ? "ist sie"
              : "ist er"
            : "sind sie"
        } dir wert? Vielleicht <strong>${amountStr}</strong>?`
      : "",
  monthly: "Monatlich spenden?",
  ctaBtn: (timeStr, contentsStr, amountStr, storage, isMonthly) =>
    `Mit ${amountStr} danken, ${isMonthly ? "jeden Monat!" : "einmalig"}`,
  unlockBtn: "Erstmal weiterlesen",
  footer: (timeStr) =>
    `* Lesezeit insgesamt auf dekoder: ${timeStr}. Diese Daten werden nur in deinem Browser gespeichert und nicht auf unsere Server übertragen!`,
  resetBtn: "Zähler zurücksetzen",
  feedbackTitle: "Vielen Dank für deine Spende",
  feedbackBody:
    "Gerade für uns als gemeinnütziges Projekt ist das Engagement unserer Leserinnen und Leser besonders wertvoll und wir freuen uns, dass du uns unterstützt – vielen Dank! Wir setzen nun deinen Zähler zurück ...",
  feedbackBtn: "OK",
  backBtn: "Zurück",
  credit: `developed by <a href="https://www.dekoder.org/" target="_blank">dekoder</a>`,
  otherPaymentMethods: "andere Zahlungswege",
  paypalSingleName: "einmalige Spende",
  paypalMonthlyName: "monatliche Spende",
};

Custom Styling

Add your own CSS file with according classes to overwrite the default stylings.

Use with React (experimental)

To use the donation encourager in your React project, you can also install it as an npm module:

npm install donation-encourager

And then:

import DonationEncourager, { donEnc } from "donation-encourager";

In your app's render function you could initialize the donation encourager like this:

useEffect(() => {
  donEnc("init", {
    targetSelector: ".my-article-body"
  });
  donEnc("pageview");
}, []);

return (
  <App>
    <div className="my-article-body">
      ...
    </div>
    <DonationEncourager />
  </App>
);

Make sure you use a Sass Loader (like sass-loader for Webpack) in your project.