@kwsites/cms-instagram-widgets

Instagram widget compatible with the apostrophe cms

Getting Started

Install with npm i @kwsites/cms-instagram-widgets or yarn add @kwsites/cms-instagram-widgets.

Ensure your application also has a dependency on @kwsites/cms-common, which provides the less plugins used by this library to generate its theme.

Add both libraries to your app.js:

// app.js
apostrophe({
  modules: {
    '@kwsites/cms-common': {},
    '@kwsites/cms-instagram-widgets': {
      embed: { source: '...', token: '...' },
      auth: { /* see authentication below */ }
    },
  }
});

To use the widget in an area:

<!-- in any template.html -->
{{
  apos.area(
    data.page,
    "myAreaName",
    {
      widgets: {
        "@kwsites/cms-instagram": {
        }
      }
    }
  )
}}

Authentication

Periodically instagram will require that a valid Instagram account has logged into the site for the IP and "device" to show profile data. To manage the interaction with Instagram, this library uses instagram-private-api. Configure your account username/password using one of the options below:

With source=inline, the username and password are used as-is from the module's configuration in app.js:

To be able to reliably fetch oembed data from instagram, you should follow the steps on https://developers.facebook.com/docs/instagram/oembed/ to create a Facebook app then supply the app's access token using the embed configuration property - either supplying the token itself (when source=inline) or the name of the environment variable to look up (when source=env).

const config = {
  auth: { source: 'inline', user: 'USERNAME', pass: 'PASSWORD' },
  embed: { source: 'env', token: 'OEMBED_TOKEN' }
};

With source=env, the username and password are read from the named environment variables:

process.env.IG_USER = 'USERNAME';
process.env.IG_PASS = 'PASSWORD';
const auth = { source: 'env', user: 'IG_USER', pass: 'IG_PASS' };

// set your auth options in the app.js configuration of the module
apostrophe({ modules: { '@kwsites/cms-instagram-widgets': { auth, embed } } });

For a completely custom way to deliver your credentials, extend the module:

apostrophe({ modules: { '@kwsites/cms-instagram-widgets': {
   construct (self, options) {
      // override the validation logic,
      // returning a non-empty string is deemed a validation failure
      self.validateAuthConfig = (req) => '';

      // get the username and password as a string array
      self.getApiAuth = () => ['USERNAME', 'PASSWORD'];
   }
 } } });

Configuration Options

Options passed into the module configuration in your app.js:

• auth: { source: 'inline' | 'env'; user: string; pass: string } sets the source of your instagram authentication credentials, can be omitted entirely to fetch as a guest (note that guest access will likely not work in production due to rate limiting etc)

• cacheTTL: number = 86400 sets the duration (in seconds) a profile gallery should be cached before re-fetching

• cacheEnabled: boolean = true optionally disable the ability to cache profile galleries

• errorTTL: number = 1200 sets the duration (in seconds) to wait before reattempting to load a profile gallery that returned an error.

• embed: { source: 'inline' | 'env'; token: string } configure the instagram oembed app token to pass to instagram on request

• offline: boolean optionally disable the gallery view by setting offline to true

Offline Mode

Set the global apos.options.locals.offline to true by adding offline: true to your data/local.js to prevent attempting to fetch profiles remotely, useful when working offline to return early rather than attempt to connect to the remote instagram server.

Post-Install

At the time of publishing, Apostrophe CMS doesn't automatically support @scoped/ dependency modules, which causes an error when the CMS starts up and is unable to symlink the source of the modules into the /public folder correctly.

To resolve this, you need to manually create the directory /public/modules/@kwsites before starting the server. To have this run automatically after installing dependencies, add the following to your package.json scripts block:

{
  "scripts": {
    "postinstall": "mkdir -p ./public/modules/@kwsites"
  }
}

Troubleshooting

This library uses debug to manage its logging, enable the log by running your application with the DEBUG environment variable:

$ DEBUG=@kwsites/cms-instagram-widgets:* node app.js

Alternatively, set the verbose option for this module in your app.js:

// app.js
apostrophe({
  modules: {
    '@kwsites/cms-common': {},
    '@kwsites/cms-instagram-widgets': { verbose: true },
  }
});