/act-now-links-service

Generate sharable links with meta tags and dynamic preview images.

Primary LanguageTypeScript

Act Now Links Service

Service to generate sharable links with meta tags and dynamic preview images.

Contents

API

Setup

Insomnia

API

API base URL: https://share.actnowcoalition.org

Creating a share link

Registers a new share link with meta tags according to the request body params, or returns the existing one if a share link already exists for the supplied parameters. On success, returns the URL of the new or existing share link.

Requires a valid API key. If you do not have a key and would like to register one, or you have forgotten yours, please reach out to us.

Request

  • URL: /api/registerUrl
  • Method: POST
  • Headers
    • Required: Content-Type: 'application/json'
Data Parameters
Parameter Data Type Description Required
url string Url to create share link for true
title string Title meta tag false
description string Description meta tag false
imageUrl string Url of image to use as image meta tag false
imageHeight number Height of preview image (imageUrl) in pixels false
imageHeight number Width of preview image (imageUrl) in pixels false
apiKey string Valid API key to authorize the request.
Can also be passed as a query parameter using ?apiKey=API_KEY_HERE.		 true

Success response

Returns new or existing share link for the URL provided with meta tags according to the data params.

  • Code: 200
  • Content: <share link URL>

Error Response

  • Code: 400 Missing or invalid URL parameter. <br />

Example

./payload.json
{
  "url": "https://www.covidactnow.org",
  "title": "Covid Act Now - US Covid Data Tracker",
  "description": "See how Covid is spreading in your community",
  "imageUrl": "https://covidactnow.org/internal/share-image/states/ma"
}
curl -v -X POST -H "Content-Type:application/json" https://share.actnowcoalition.org/registerUrl?apiKey=API_KEY_HERE -d @./payload.json

Fetching all existing share links for a URL

Returns all the share links with the same URL as the supplied target URL, or an empty object if none exist.

Request

  • URL: /api/shareLinksByUrl?url=<target-URL>
  • Method: GET

Success Response

Returns all corresponding share links for the URL provided.

  • Code: 200
  • Content: { urls: {share-link-url: { share-link-fields }} }

Example

curl -v -X GET "https://share.actnowcoalition.org/shareLinksByUrl?url=https://www.covidactnow.org"

Taking a screenshot of a share image page

Generates a screenshot of the given target URL and returns the image.

The target page must contain an element with screenshot as a CSS class name to indicate where the screenshot will be captured. Because components on the target page can take time to load, the endpoint also uses specific class names to tell when the page is ready to be captured. The screenshot is captured when:

  • an instance of the act-now-component-loaded CSS class is detected on the page
  • no instances of the act-now-component-loading CSS classes are detected

If you are capturing a page with multiple components that take time to load, append act-now-component-loading classes to the components while they are loading, and act-now-component-loaded classes when they finish loading. To see how this can be implemented, see an example act-now-packages component.

We can combine this endpoint with /api/registerUrl to create share links with dynamic images by supplying an api/screenshot/ URL as the imageUrl data param when creating a new share link.

Request

  • URL: /api/screenshot?url=<target-URL>
  • Method: GET

Success Response

Serves screenshot of targeted URL to request URL.

  • Code: 200
  • Content: <screenshot of target URL as .PNG>

Example

curl -v -X GET "https://share.actnowcoalition.org/screenshot?url=https://covidactnow.org/internal/share-image/states/ma" > img.png

Setup

Getting Started

To get setup:

  • If applicable, make sure you have access to the act-now-links-dev Google Firebase project.
  • Clone the repo with: git clone https://github.com/covid-projections/act-now-links-service.git
  • Move to the repo directory: cd act-now-links-service
  • Install firebase tools and CLI: yarn global add firebase-tools
  • Login to firebase: firebase login, this will open a browser to sign in through in order to give you authentication to interact with the project.
  • Make sure that you are using Node 16
  • cd functions/ && yarn
  • Run yarn serve to start the emulators

Running emulators for local development

For local development, we can run emulators such that we do not need to deploy our changes to the production at every step.

  • Start the emulators with firebase emulator:start. The firestore emulator relies on Java, so if you encounter an error like The operation couldn’t be completed. Unable to locate a Java Runtime. it is either because you do not have Java installed, or the installation cannot be found.
    • If you do not have Java installed, install it with brew install Java (on Mac). On completion, run java; if the same error is raised as above, follow the next step, otherwise skip it.
    • To locate/link to your Java installation run sudo ln -sfn /opt/homebrew/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk (see this StackOverflow post for context).
    • Re-run firebase emulator:start to hopefully see that the start is successful.
  • Once the emulators are running you can interact with the local instance the same as you would production, following the ports/locations specified in the terminal. By default, the functions emulator is set to run on localhost:5001, creating endpoints at localhost:5001/act-now-links-dev/central-us1/api.
  • The emulator will update whenever the project is built. We can have changes applied on save by running yarn build:watch in functions/ in a separate terminal window.

Deploying changes

Deploys are handled automatically by the Firebase functions deploy Github action. The workflow is triggered on pushes to the main and develop branches so that the deployed functions will reflect the most up-to-date status of the repository.

If need be, you can deploy functions yourself by running yarn deploy in functions/, but this is generally discouraged as it disrupts the symmetry between Github and Firebase.

Insomnia

Insomnia can be used to test, debug, and store requests. To download and install the Insomnia client see https://insomnia.rest/download.

To work with the Act Now Links Service API in Insomnia, go to the main dashboard screen (e.g. by clicking "Insomnia" at the top of the screen) and select Create > Import From > File and select functions/insomnia-config.yaml.