@enlay/node v2.0.0
enlay-node
JavaScript library for the Enlay API.
Installation
Yarn
yarn add @enlay/node
NPM
npm install @enlay/node
Usage
To be fully integrated with Enlay, we have composed a list of actionables below. These are essential for your integration to work. Currently, there are two implementations required, one for the backend and one for the frontend. On the backend we handle user product fetching and generating advertisement placements. Meanwhile, on the frontend, we register clicks and views of those products..
Backend
Creating the enlay client
You should not expose the Enlay client with your token to the user. You can find your token on the publisher dashboard.
// src/enlay/index.ts
import Enlay from "@enlay/node";
const enlay = new Enlay({
apiToken: "ey5ab...",
});
export default enlay;
Fetching advertisement placements
A placement is an advertisement which is currently running. There are a few options you can provide to create placements to fit your own use case but in this example we fetch 2 unique on-going advertisements. From these placements, you can then extract your related resource ID through the custom fields as shown in the real world example.
The slot-id
can be found on your publisher dashboard.
// src/products.ts
import enlay from "./enlay";
app.get(`/products`, (req, res) => {
// Fetch the advertisement placements
const _placements = await enlay.slots.createPlacements(slotId, {
max: 1,
unique: true,
});
// ...Fetch products and send to client
});
Real world advanced example with data using knex.
Typically, you might have another route to fetch sponsored products or an additional query param such as /products?sponsored=true
. Although, in this example, it shows how you would attach sponsored products in with a regular product serving.
// src/products.ts
import enlay from "./enlay";
app.get(`/products`, (req, res) => {
const products = await knex("products").select("*").limit(20);
// Fetch the advertisement placements
const placements = await enlay.slots.createPlacements(slotId, {
max: 1,
unique: true,
});
// Fetch the correlated product ids
const productIds = data.createPlacements.map((placement) => {
return placement.advertisement.customFields["id"];
});
// Fetch the sponsored products
const sponsoredProducts = await knex("products")
.select("*")
.whereIn("id", productIds);
// Append placement identifier to product
const sponsored = sponsoredProducts.map((product) => {
const placement = data.createPlacements.find(
(placement) => placement.advertisement.customFields.id === product.id
);
return {
...product,
placementId: placement?.id,
};
});
// Products could overlap so may need to filter
return res.json([...sponsored, ...products]);
});
Creating webhook endpoint for fetching users promotables
This endpoint is needed so we know what products an advertiser can sponsor on your platform. This will then be used when advertisers visit the whitelabelled Enlay platform to pick and choose which advertisement they want to promote. The url can be completely bespoke and is not limited to /enlay/products
.
// src/enlay/products.ts
import enlay from "./enlay";
import { Events, Entities } from "@enlay/node";
app.post(`/enlay/products`, (req, res) => {
// Construct the enlay event
const {
data: { promotable },
} = enlay.webhooks.constructEvent<Events.GetPromotablesPayload>(req.body);
// Get the advertiser email (other fields are available)
const { email } = promotable.advertiser;
// Fetch the user
const user = await knex("users")
.select("*")
.where({
email,
})
.first();
if (!user) {
return res.json([]);
}
// Fetch the users products in specific format
const products: Entities.PromotablePayload[] = await knex("products")
.select(["id", "name as display_name"])
.where({
user_id: user.id,
});
return res.json(products);
});
Frontend (React - NextJS)
Creating the enlay client
Create the client without any options. This is safe to share as it does not have the API token attached.
// src/enlay/index.ts
import Enlay from "@enlay/node";
const enlay = new Enlay();
export default enlay;
Registering advertisement click
Clicks are one of the core parts of the analytics for advertisers. In this example, it fires off a click on a product to enlay asynchronously.
import React from "react";
import enlay from "../enlay";
// src/pages/products.ts
export default function Products() {
const { data: products } = useProducts();
const router = useRouter();
return (
<>
{products.map((product) => (
<Product
product={product}
onClick={() => {
// Fire a placement click async
if (product.placementId) {
enlay.placements.clickPlacement(product.placementId);
}
router.push(`/products/${product.id}`);
}}
/>
))}
</>
);
}
(Optional) Registering advertisement view
Views are also core for advertisers as these are true impressions. In this example, on initial mount, we are registering views on all rendered products. This gives an advertiser and publisher insights on true impressions on products. In the future we hope to add more such as registering views when a product is scrolled into view etc.
import React, { useEffect } from "react";
import enlay from "../enlay";
// src/pages/products.ts
export default function Products() {
const { data: products } = useProducts();
const router = useRouter();
// Register views on all the products on first render
useEffect(() => {
async function registerView() {
await enlay.placements.viewPlacements(
products
.filter((product) => !!p.placementId)
.map((product) => product.placementId)
);
}
registerView();
}, []);
return (
<>
{products.map((product) => (
<Product product={product} />
))}
</>
);
}