@saltcorn/meta-marketing-api 0.1.0 → 0.1.1

package/README.md

@@ -133,6 +133,9 @@ a different token.
 | `get_meta_ad(adId, query)` | One ad |
 | `get_meta_ad_creatives(accountId, query)` | The creatives in an ad account |
 | `get_meta_ad_creative(creativeId, query)` | One creative |
+| `get_meta_ad_headline(ad)` | The headline of an ad, from an ad id or an ad you have already read |
+| `get_meta_ad_body(ad)` | The primary text of an ad: the longer wording above the image |
+| `get_meta_ad_text(ad)` | Both of the above together, as `{ headline, body }`, in one read |
 | `get_meta_ad_preview(adId, adFormat)` | A ready made HTML preview of an ad |
 | `get_meta_insights(objectId, query)` | Performance figures for an account, campaign, ad set or ad |
 | `get_meta_insights_async(objectId, query)` | The same, run as a background report, for large date ranges |
@@ -164,6 +167,21 @@ get_meta_ads("", {
 })
 ```
 
+The wording of an ad is not in the ad itself, it sits on the creative, and
+Meta keeps it in a different place for each kind of ad. `get_meta_ad_text`
+finds it for you, wherever it is:
+
+```
+get_meta_ad_text(ad_id)
+```
+
+which gives you `{ headline: "...", body: "..." }`, where the body is the
+longer text above the image. For an ad that is boosting a post already on
+your page, the wording belongs to the post rather than to the ad, and reading
+it needs a token that can also read the page. When it cannot be read you get
+empty text back rather than an error; `get_meta_ad_preview` will still show
+you the ad as it appears.
+
 ## Things to know
 
 - **Money is in cents.** Budgets, bids and amounts spent come from Meta as

package/api.js

@@ -91,9 +91,24 @@ const DEFAULT_FIELDS = {
     "call_to_action_type",
     "effective_object_story_id",
     "object_story_spec",
+    "asset_feed_spec",
   ],
 };
 
+// Where the wording of an ad can be found: the headline, and the primary text
+// that runs above the image. Meta puts both in a different place depending on
+// how the ad was built, and nowhere at all on the creative when the ad
+// promotes a post that already exists on the page.
+const CREATIVE_TEXT_FIELDS = [
+  "id",
+  "name",
+  "title",
+  "body",
+  "object_story_spec",
+  "asset_feed_spec",
+  "effective_object_story_id",
+];
+
 // Metrics that are valid at every insights level.
 const BASE_INSIGHTS_FIELDS = [
   "impressions",
@@ -420,6 +435,105 @@ const getAdPreview = async (adId, adFormat, cfg) => {
   return json?.data?.[0]?.body || "";
 };
 
+/**
+ * Pull every headline out of a creative, best first. A carousel has one per
+ * card and a dynamic creative can carry several for Meta to choose between,
+ * so this returns a list rather than a single string.
+ */
+const creativeHeadlines = (creative) => {
+  const spec = creative?.object_story_spec || {};
+  const found = [
+    creative?.title,
+    spec.link_data?.name,
+    spec.video_data?.title,
+    spec.template_data?.name,
+    ...(spec.link_data?.child_attachments || []).map((c) => c.name),
+    ...(creative?.asset_feed_spec?.titles || []).map((t) => t.text),
+  ];
+  return [...new Set(found.filter((h) => h))];
+};
+
+/**
+ * Pull every primary text out of a creative, best first. This is the longer
+ * wording that runs above the image, which Meta calls the primary text in Ads
+ * Manager and the body or the message in its API. As with headlines, a
+ * dynamic creative can carry several.
+ */
+const creativeBodies = (creative) => {
+  const spec = creative?.object_story_spec || {};
+  const found = [
+    creative?.body,
+    spec.link_data?.message,
+    spec.video_data?.message,
+    spec.photo_data?.caption,
+    spec.text_data?.message,
+    spec.template_data?.message,
+    ...(creative?.asset_feed_spec?.bodies || []).map((b) => b.text),
+  ];
+  return [...new Set(found.filter((b) => b))];
+};
+
+/**
+ * The wording of the page post an ad promotes: the post's own text, and the
+ * headline of the link it carries.
+ */
+const storyText = async (storyId, cfg) => {
+  const json = await graphFetch(
+    `/${storyId}`,
+    { query: { fields: "message,attachments{title,description}" } },
+    cfg
+  );
+  const attachment = json?.attachments?.data?.[0] || {};
+  return {
+    headline: attachment.title || "",
+    body: json?.message || attachment.description || "",
+  };
+};
+
+/**
+ * The wording of an ad: { headline, body }, where body is the primary text
+ * above the image. Takes an ad id, or an ad that has already been read with
+ * its creative, in which case nothing is read again.
+ *
+ * Ads that promote a post which already exists on the page keep their wording
+ * on the post, which needs a second read and a token with access to the page.
+ * When that read is not allowed the wording comes back empty rather than
+ * throwing.
+ */
+const getAdText = async (ad, cfg) => {
+  let creative = typeof ad === "object" ? ad?.creative : null;
+  if (!creative?.object_story_spec && !creative?.title && !creative?.body) {
+    const fetched = await graphFetch(
+      `/${typeof ad === "object" ? ad?.id : ad}`,
+      { query: { fields: `creative{${CREATIVE_TEXT_FIELDS.join(",")}}` } },
+      cfg
+    );
+    creative = fetched?.creative;
+  }
+  const text = {
+    headline: creativeHeadlines(creative)[0] || "",
+    body: creativeBodies(creative)[0] || "",
+  };
+  if ((!text.headline || !text.body) && creative?.effective_object_story_id)
+    try {
+      const story = await storyText(creative.effective_object_story_id, cfg);
+      return {
+        headline: text.headline || story.headline,
+        body: text.body || story.body,
+      };
+    } catch (e) {
+      if (cfg?.log_requests)
+        console.log("Meta: could not read the post behind the ad", e.message);
+    }
+  return text;
+};
+
+/** The headline of an ad, as getAdText */
+const getAdHeadline = async (ad, cfg) => (await getAdText(ad, cfg)).headline;
+
+/** The primary text of an ad, the wording above the image, as getAdText */
+const getAdBody = async (ad, cfg) => (await getAdText(ad, cfg)).body;
+
 //
 // Insights
 //
@@ -523,6 +637,7 @@ module.exports = {
   GRAPH_HOST,
   DEFAULT_API_VERSION,
   DEFAULT_FIELDS,
+  CREATIVE_TEXT_FIELDS,
   BASE_INSIGHTS_FIELDS,
   INSIGHTS_LEVEL_FIELDS,
   NUMERIC_INSIGHTS_FIELDS,
@@ -551,6 +666,12 @@ module.exports = {
   getAdCreatives,
   getAdCreative,
   getAdPreview,
+  creativeHeadlines,
+  creativeBodies,
+  storyText,
+  getAdText,
+  getAdHeadline,
+  getAdBody,
   getInsights,
   startInsightsReport,
   getReportRun,

package/index.js

@@ -24,6 +24,9 @@ const {
   getAdCreatives,
   getAdCreative,
   getAdPreview,
+  getAdText,
+  getAdHeadline,
+  getAdBody,
   getInsights,
   getInsightsAsync,
   exchangeLongLivedToken,
@@ -383,6 +386,33 @@ module.exports = {
         { name: "query", type: "JSON" },
       ],
     },
+    get_meta_ad_headline: {
+      async run(ad, cfgOverRide) {
+        return await getAdHeadline(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "Get the headline of an ad, wherever Meta keeps it for that kind of ad. Takes an ad id or an ad row that already has its creative.",
+      arguments: [{ name: "ad", type: "String" }],
+    },
+    get_meta_ad_body: {
+      async run(ad, cfgOverRide) {
+        return await getAdBody(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "Get the primary text of an ad, the longer wording above the image. Takes an ad id or an ad row that already has its creative.",
+      arguments: [{ name: "ad", type: "String" }],
+    },
+    get_meta_ad_text: {
+      async run(ad, cfgOverRide) {
+        return await getAdText(ad, { ...cfg, ...cfgOverRide });
+      },
+      isAsync: true,
+      description:
+        "Get the headline and the primary text of an ad together, as { headline, body }, in one read",
+      arguments: [{ name: "ad", type: "String" }],
+    },
     get_meta_ad_preview: {
       async run(adId, adFormat, cfgOverRide) {
         return await getAdPreview(adId, adFormat, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saltcorn/meta-marketing-api",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Read ads on Facebook and Instagram with the Meta Marketing API",
   "main": "index.js",
   "dependencies": {

package/tests/api.test.js

@@ -6,6 +6,8 @@ const {
   isTransientError,
   insightsFields,
   DEFAULT_FIELDS,
+  creativeHeadlines,
+  creativeBodies,
 } = require("../api");
 
 describe("query string encoding", () => {
@@ -92,3 +94,110 @@ describe("default fields", () => {
     });
   });
 });
+
+describe("finding the headline on a creative", () => {
+  it("reads the headline of a link ad", () => {
+    expect(
+      creativeHeadlines({
+        object_story_spec: {
+          link_data: { name: "Half price today", message: "Primary text" },
+        },
+      })
+    ).toEqual(["Half price today"]);
+  });
+  it("reads the headline of a video ad", () => {
+    expect(
+      creativeHeadlines({ object_story_spec: { video_data: { title: "Watch" } } })
+    ).toEqual(["Watch"]);
+  });
+  it("reads the old style title field", () => {
+    expect(creativeHeadlines({ title: "Legacy headline" })).toEqual([
+      "Legacy headline",
+    ]);
+  });
+  it("returns one headline per carousel card", () => {
+    expect(
+      creativeHeadlines({
+        object_story_spec: {
+          link_data: {
+            name: "Our shop",
+            child_attachments: [{ name: "Shoes" }, { name: "Hats" }],
+          },
+        },
+      })
+    ).toEqual(["Our shop", "Shoes", "Hats"]);
+  });
+  it("returns every headline of a dynamic creative, without repeats", () => {
+    expect(
+      creativeHeadlines({
+        title: "Half price",
+        asset_feed_spec: {
+          titles: [{ text: "Half price" }, { text: "50% off" }],
+        },
+      })
+    ).toEqual(["Half price", "50% off"]);
+  });
+  it("comes back empty when there is no headline to find", () => {
+    expect(creativeHeadlines({ effective_object_story_id: "1_2" })).toEqual([]);
+    expect(creativeHeadlines(null)).toEqual([]);
+  });
+});
+
+describe("finding the primary text on a creative", () => {
+  it("reads the text above the image of a link ad", () => {
+    expect(
+      creativeBodies({
+        object_story_spec: {
+          link_data: { name: "A headline", message: "The longer wording" },
+        },
+      })
+    ).toEqual(["The longer wording"]);
+  });
+  it("reads the text of video, photo and text only ads", () => {
+    expect(
+      creativeBodies({ object_story_spec: { video_data: { message: "Video" } } })
+    ).toEqual(["Video"]);
+    expect(
+      creativeBodies({ object_story_spec: { photo_data: { caption: "Photo" } } })
+    ).toEqual(["Photo"]);
+    expect(
+      creativeBodies({ object_story_spec: { text_data: { message: "Text" } } })
+    ).toEqual(["Text"]);
+  });
+  it("reads the old style body field", () => {
+    expect(creativeBodies({ body: "Legacy body" })).toEqual(["Legacy body"]);
+  });
+  it("returns every primary text of a dynamic creative, without repeats", () => {
+    expect(
+      creativeBodies({
+        body: "Shop the sale",
+        asset_feed_spec: {
+          bodies: [{ text: "Shop the sale" }, { text: "Everything reduced" }],
+        },
+      })
+    ).toEqual(["Shop the sale", "Everything reduced"]);
+  });
+  it("does not mistake the headline for the primary text", () => {
+    const creative = {
+      title: "A headline",
+      object_story_spec: { link_data: { name: "A headline" } },
+    };
+    expect(creativeBodies(creative)).toEqual([]);
+    expect(creativeHeadlines(creative)).toEqual(["A headline"]);
+  });
+  it("comes back empty when there is no text to find", () => {
+    expect(creativeBodies({ effective_object_story_id: "1_2" })).toEqual([]);
+    expect(creativeBodies(null)).toEqual([]);
+  });
+});
+
+describe("default fields", () => {
+  it("asks for the dynamic creative assets", () => {
+    expect(DEFAULT_FIELDS.adcreative).toContain("asset_feed_spec");
+    expect(DEFAULT_FIELDS.adcreative).toContain("effective_object_story_id");
+  });
+  it("asks for both the headline and the primary text", () => {
+    expect(DEFAULT_FIELDS.adcreative).toContain("title");
+    expect(DEFAULT_FIELDS.adcreative).toContain("body");
+  });
+});