@pipedream/linkedin_ads 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,11 @@
+# Overview
+
+The LinkedIn Ads API on Pipedream enables you to automate and integrate your LinkedIn advertising efforts with other services. Fetch campaign data, manage ad accounts, or automate ad creation and adjustments. With Pipedream, you can trigger workflows with HTTP requests, emails, and on a schedule, and connect to thousands of other apps with minimal effort.
+
+# Example Use Cases
+
+- **Sync LinkedIn Ad Campaigns to Google Sheets**: Automate the syncing of LinkedIn Ad campaign data into a Google Sheets spreadsheet. This workflow makes it easy to analyze ad performance, share reports with your team, and maintain records without manual data entry.
+
+- **LinkedIn Ad Performance Alerts via Slack or Email**: Set up a workflow that monitors your LinkedIn Ad campaigns for key performance metrics, and sends an alert via Slack or Email when your ads meet certain criteria, such as cost per click (CPC) thresholds or impressions goals, ensuring prompt reaction to ad performance.
+
+- **Automatic Ad Pausing Based on Budget Constraints**: Create a workflow that checks your LinkedIn Ad spend against your set budget and automatically pauses campaigns if spend exceeds your budget. This helps maintain control over your advertising costs without needing to check in manually.

package/actions/common/report.mjs

@@ -0,0 +1,62 @@
+/* eslint-disable no-unused-vars */
+import app from "../../linkedin_ads.app.mjs";
+import utils from "../../common/utils.mjs";
+
+export default {
+  props: {
+    app,
+  },
+  methods: {
+    getDateStr(date) {
+      return [
+        `day:${date.getDate()}`,
+        `month:${date.getMonth() + 1}`,
+        `year:${date.getFullYear()}`,
+      ].join(",");
+    },
+    getDateRangeParam(startStr, endStr) {
+      const { getDateStr } = this;
+      const start = getDateStr(new Date(startStr));
+
+      if (!endStr) {
+        return `(start:(${start}))`;
+      }
+
+      const end = getDateStr(new Date(endStr));
+      return `(start:(${start}),end:(${end}))`;
+    },
+    getListParam(list = []) {
+      return `List(${list?.map(encodeURIComponent).join(",")})`;
+    },
+    getListParams(props = {}) {
+      return Object.entries(props)
+        .reduce((acc, [
+          key,
+          value,
+        ]) => {
+          if (
+            typeof(value) === "function"
+            || value === undefined
+            || value === null
+          ) {
+            return acc;
+          }
+          return {
+            ...acc,
+            [key]: this.getListParam(
+              typeof(value) === "string"
+                ? JSON.parse(value)
+                : value,
+            ),
+          };
+        }, {});
+    },
+    createReport(args = {}) {
+      return this.app._makeRequest({
+        path: "/adAnalytics",
+        paramsSerializer: utils.getParamsSerializer(),
+        ...args,
+      });
+    },
+  },
+};

package/actions/create-report/create-report.mjs

@@ -0,0 +1,105 @@
+/* eslint-disable no-unused-vars */
+import common from "../common/report.mjs";
+
+export default {
+  ...common,
+  key: "linkedin_ads-create-report",
+  name: "Create A Report",
+  description: "Queries the Analytics Finder to get analytics for the specified entity i.e company, account, campaign. [See the docs here](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting#analytics-finder)",
+  version: "0.0.4",
+  type: "action",
+  props: {
+    ...common.props,
+    adAccountId: {
+      propDefinition: [
+        common.props.app,
+        "adAccountId",
+      ],
+    },
+    pivot: {
+      propDefinition: [
+        common.props.app,
+        "pivot",
+      ],
+    },
+    timeGranularity: {
+      propDefinition: [
+        common.props.app,
+        "timeGranularity",
+      ],
+    },
+    dateRangeStart: {
+      type: "string",
+      label: "Date Range Start",
+      description: "Represents the inclusive start time range of the analytics. If unset, it indicates an open range up to the end time. Should be in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g. 2022-12-27.",
+    },
+    dateRangeEnd: {
+      type: "string",
+      label: "Date Range End",
+      description: "Represents the inclusive end time range of the analytics. Must be after start time if it's present. If unset, it indicates an open range from start time to everything after. Should be in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g. 2022-12-27.",
+      optional: true,
+    },
+    shares: {
+      type: "string[]",
+      label: "Shares",
+      description: "An [Array of Share URN](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/community-management/shares/share-api). Required unless another facet is provided.",
+      optional: true,
+    },
+    campaigns: {
+      type: "string[]",
+      label: "Campaigns",
+      description: "An [Array of Sponsored Campaign URN](https://docs.microsoft.com/en-us/linkedin/shared/references/v2/ads/adcampaigns?context=linkedin/marketing/context). Required unless another facet is provided.",
+      optional: true,
+    },
+    creatives: {
+      type: "string[]",
+      label: "Creatives",
+      description: "An [Array of Sponsored Creative URN](https://docs.microsoft.com/en-us/linkedin/shared/references/v2/ads/adcreatives?context=linkedin/marketing/context). Required unless another facet is provided.",
+      optional: true,
+    },
+    campaignGroups: {
+      type: "string[]",
+      label: "Campaign Groups",
+      description: "An [Array of Campaign Group URN](https://docs.microsoft.com/en-us/linkedin/shared/references/v2/ads/adcampaigngroups?context=linkedin/marketing/context). Required unless another facet is provided.",
+      optional: true,
+    },
+    accounts: {
+      propDefinition: [
+        common.props.app,
+        "accounts",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      getDateRangeParam,
+      getListParams,
+      createReport,
+      adAccountId,
+      pivot,
+      timeGranularity,
+      dateRangeStart,
+      dateRangeEnd,
+      ...arrayProps
+    } = this;
+
+    const response = await createReport({
+      $,
+      params: {
+        q: "analytics",
+        pivot,
+        timeGranularity,
+        dateRange: getDateRangeParam(dateRangeStart, dateRangeEnd),
+        ...getListParams(arrayProps),
+      },
+    });
+
+    $.export("$summary", `Successfully retrieved analytics information with ${response.elements.length} elements.`);
+
+    return response.elements;
+  },
+};

package/actions/create-report-by-advertiser-account/create-report-by-advertiser-account.mjs

@@ -0,0 +1,60 @@
+/* eslint-disable no-unused-vars */
+import common from "../common/report.mjs";
+
+export default {
+  ...common,
+  key: "linkedin_ads-create-report-by-advertiser-account",
+  name: "Create Report By Advertiser Account",
+  description: "Sample query using analytics finder that gets analytics for a particular account for date range starting in a given year. [See the docs here](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting#sample-request)",
+  version: "0.0.4",
+  type: "action",
+  props: {
+    ...common.props,
+    startYear: {
+      propDefinition: [
+        common.props.app,
+        "startYear",
+      ],
+    },
+    timeGranularity: {
+      propDefinition: [
+        common.props.app,
+        "timeGranularity",
+      ],
+    },
+    adAccountId: {
+      propDefinition: [
+        common.props.app,
+        "adAccountId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      getDateRangeParam,
+      startYear,
+      timeGranularity,
+      adAccountId,
+      getListParam,
+      createReport,
+    } = this;
+
+    const response = await createReport({
+      $,
+      params: {
+        "q": "analytics",
+        "pivot": "ACCOUNT",
+        "dateRange": getDateRangeParam(`${startYear}-01-01`),
+        timeGranularity,
+        "accounts": getListParam([
+          app.getSponsoredAccountUrn(adAccountId),
+        ]),
+      },
+    });
+
+    $.export("$summary", "Successfully retrieved analytics");
+
+    return response;
+  },
+};

package/actions/create-report-by-campaign/create-report-by-campaign.mjs

@@ -0,0 +1,69 @@
+/* eslint-disable no-unused-vars */
+import common from "../common/report.mjs";
+
+export default {
+  ...common,
+  key: "linkedin_ads-create-report-by-campaign",
+  name: "Query Analytics Finder Campaign Sample",
+  description: "Sample query using analytics finder that gets analytics for a particular campaign in a date range starting in a given year. [See the docs here](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting#analytics-finder)",
+  version: "0.0.4",
+  type: "action",
+  props: {
+    ...common.props,
+    startYear: {
+      propDefinition: [
+        common.props.app,
+        "startYear",
+      ],
+    },
+    timeGranularity: {
+      propDefinition: [
+        common.props.app,
+        "timeGranularity",
+      ],
+    },
+    adAccountId: {
+      propDefinition: [
+        common.props.app,
+        "adAccountId",
+      ],
+    },
+    campaignId: {
+      propDefinition: [
+        common.props.app,
+        "campaignId",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      getDateRangeParam,
+      startYear,
+      timeGranularity,
+      campaignId,
+      getListParam,
+      createReport,
+    } = this;
+
+    const response = await createReport({
+      $,
+      params: {
+        "q": "analytics",
+        "pivot": "CAMPAIGN",
+        "dateRange": getDateRangeParam(`${startYear}-01-01`),
+        timeGranularity,
+        "campaigns": getListParam([
+          app.getSponsoredCampaignUrn(campaignId),
+        ]),
+      },
+    });
+
+    $.export("$summary", "Successfully retrieved analytics");
+
+    return response;
+  },
+};

package/actions/send-conversion-event/send-conversion-event.mjs

@@ -0,0 +1,149 @@
+import { createHash } from "crypto";
+import app from "../../linkedin_ads.app.mjs";
+
+export default {
+  key: "linkedin_ads-send-conversion-event",
+  name: "Send Conversion Event",
+  description: "Sends a conversion event to LinkedIn Ads. [See the documentation](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api?view=li-lms-2024-01&tabs=http#streaming-conversion-events)",
+  version: "0.0.3",
+  type: "action",
+  props: {
+    app,
+    adAccountId: {
+      propDefinition: [
+        app,
+        "adAccountId",
+      ],
+    },
+    conversionId: {
+      propDefinition: [
+        app,
+        "conversionId",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+    conversionHappenedAt: {
+      type: "string",
+      label: "Conversion Happened At",
+      description: "Epoch timestamp in milliseconds at which the conversion event happened. Note: If your source records conversion timestamp in seconds, please insert 000 at the end to transform it to milliseconds. Eg. `1590739275000`.",
+    },
+    email: {
+      type: "string",
+      label: "Email",
+      description: "Email address of the contact associated with the conversion event which needs to be in SHA256 format, a HEX encoded string with a maximum length of 64 characters. Eg. `test@example.com`.",
+    },
+    firstName: {
+      type: "string",
+      label: "First Name",
+      description: "The first name of the contact to match the conversion.",
+    },
+    lastName: {
+      type: "string",
+      label: "Last Name",
+      description: "The last name of the contact to match the conversion.",
+    },
+    conversionValueCurrencyCode: {
+      type: "string",
+      label: "Conversion Value Currency Code",
+      description: "The currency code of the conversion value in ISO format. Eg. `USD`.",
+    },
+    conversionValueAmount: {
+      type: "string",
+      label: "Conversion Value Amount",
+      description: "The value of the conversion in decimal string. If you set this field, you must also set in the **Conversion Value Currency Code** field. Eg. `100.05`.",
+    },
+    companyName: {
+      type: "string",
+      label: "Company Name",
+      description: "A plain text string representing the company of the contact to match.",
+      optional: true,
+    },
+    title: {
+      type: "string",
+      label: "Title",
+      description: "A plain text string representing the title name of the contact to match. Eg. `Software Engineer`.",
+      optional: true,
+    },
+    countryCode: {
+      type: "string",
+      label: "Country Code",
+      description: "An ISO standardized [two letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) representing the country of the contact to match. Eg. `US`.",
+      optional: true,
+    },
+    eventId: {
+      type: "string",
+      label: "Event ID",
+      description: "The unique id generated by advertisers to indicate each event. This field is used for [deduplication](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/deduplication?view=li-lms-2024-01).",
+      optional: true,
+    },
+  },
+  methods: {
+    emailToSha256(email) {
+      return createHash("sha256")
+        .update(email)
+        .digest("hex");
+    },
+    sendConversionEvent(args = {}) {
+      return this.app._makeRequest({
+        debug: true,
+        method: "POST",
+        path: "/conversionEvents",
+        ...args,
+      });
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      emailToSha256,
+      sendConversionEvent,
+      conversionId,
+      conversionHappenedAt,
+      conversionValueCurrencyCode,
+      conversionValueAmount,
+      email,
+      firstName,
+      lastName,
+      companyName,
+      title,
+      countryCode,
+      eventId,
+    } = this;
+
+    await sendConversionEvent({
+      $,
+      data: {
+        conversion: app.getConversionUrn(conversionId),
+        conversionHappenedAt: Number(conversionHappenedAt),
+        conversionValue: {
+          currencyCode: conversionValueCurrencyCode,
+          amount: conversionValueAmount,
+        },
+        user: {
+          userIds: [
+            {
+              idType: "SHA256_EMAIL",
+              idValue: emailToSha256(email),
+            },
+          ],
+          userInfo: {
+            firstName,
+            lastName,
+            companyName,
+            title,
+            countryCode,
+          },
+        },
+        eventId,
+      },
+    });
+
+    $.export("$summary", "Successfully sent conversion event to LinkedIn Ads");
+
+    return {
+      success: true,
+    };
+  },
+};

package/common/utils.mjs

@@ -0,0 +1,54 @@
+function encodeParamKeys(keys = []) {
+  return (key, value) => {
+    if (!keys.includes(key)) {
+      return `${key}=${value}`;
+    }
+    const [
+      firstPart,
+      ...otherParts
+    ] = value.split(":");
+
+    if (!firstPart?.startsWith("(")) {
+      const encoded = encodeURIComponent(value)
+        .replace("(", "%28")
+        .replace(")", "%29");
+      return `${key}=${encoded}`;
+    }
+
+    return `${key}=${firstPart}:${encodeURIComponent(otherParts.join(":"))}`;
+  };
+}
+
+function defaultEncodeFn(key, value) {
+  return `${key}=${value}`;
+}
+
+function encodeFn(key, value) {
+  return `${key}=${encodeURIComponent(value)}`;
+}
+
+function getParamsSerializer(encodeFn = defaultEncodeFn) {
+  return (params) => {
+    return Object.entries(params)
+      .map(([
+        key,
+        value,
+      ]) => encodeFn(key, value))
+      .join("&");
+  };
+}
+
+function transformResponse(jsonStr) {
+  // Regex to target specifically "id" fields, capturing
+  // the number to convert it into a string
+  // Because the number can be a long number or big integer
+  const response = jsonStr.replace(/("id"\s*:\s*)(\d+)/g, "$1\"$2\"");
+  return JSON.parse(response);
+}
+
+export default {
+  encodeParamKeys,
+  encodeFn,
+  getParamsSerializer,
+  transformResponse,
+};

package/linkedin_ads.app.mjs

@@ -123,6 +123,31 @@ export default {
         }));
       },
     },
+    leadFormId: {
+      type: "string",
+      label: "Lead Form ID",
+      description: "Select the lead form to retrieve responses for.",
+      async options({
+        page, adAccountId,
+      }) {
+        const count = 20;
+        const { elements } = await this.searchLeadForms({
+          params: {
+            q: "owner",
+            owner: `(sponsoredAccount:${this.getSponsoredAccountUrn(adAccountId)})`,
+            count,
+            start: page * count,
+          },
+        });
+        return elements.map(({
+          id,
+          name: label,
+        }) => ({
+          label,
+          value: String(id),
+        }));
+      },
+    },
   },
   methods: {
     ...app.methods,
@@ -141,6 +166,9 @@ export default {
     getEventUrn(id) {
       return `urn:li:event:${id}`;
     },
+    getVersionedLeadGenFormUrn(id, version = 1) {
+      return `urn:li:versionedLeadGenForm:(urn:li:leadGenForm:${id},${version})`;
+    },
     searchCampaigns({
       adAccountId, ...args
     } = {}) {
@@ -154,18 +182,24 @@ export default {
         "owner",
       ];
       return this._makeRequest({
-        debug: true,
         path: "/leadForms",
         paramsSerializer: utils.getParamsSerializer(utils.encodeParamKeys(keys)),
         ...args,
       });
     },
+    getLeadForm({
+      leadFormId, ...args
+    } = {}) {
+      return this._makeRequest({
+        path: `/leadForms/${leadFormId}`,
+        ...args,
+      });
+    },
     searchEvents(args = {}) {
       const keys = [
         "organizer",
       ];
       return this._makeRequest({
-        debug: true,
         path: "/events",
         paramsSerializer: utils.getParamsSerializer(utils.encodeParamKeys(keys)),
         transformResponse: utils.transformResponse,
@@ -174,7 +208,6 @@ export default {
     },
     searchConversions(args = {}) {
       return this._makeRequest({
-        debug: true,
         path: "/conversions",
         paramsSerializer: utils.getParamsSerializer(utils.encodeFn),
         ...args,
@@ -187,7 +220,6 @@ export default {
         "associatedEntity",
       ];
       return this._makeRequest({
-        debug: true,
         path: "/leadFormResponses",
         paramsSerializer: utils.getParamsSerializer(utils.encodeParamKeys(keys)),
         ...args,

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@pipedream/linkedin_ads",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Pipedream LinkedIn Ads Components",
   "main": "linkedin_ads.app.mjs",
   "keywords": [
     "pipedream",
     "linkedin_ads"
   ],
-  "files": [
-    "dist"
-  ],
   "homepage": "https://pipedream.com/apps/linkedin_ads",
   "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@pipedream/platform": "^3.0.3"
   }
 }

package/sources/new-event-registration-form-response/new-event-registration-form-response.mjs

@@ -0,0 +1,62 @@
+import { DEFAULT_POLLING_SOURCE_TIMER_INTERVAL } from "@pipedream/platform";
+import app from "../../linkedin_ads.app.mjs";
+
+export default {
+  key: "linkedin_ads-new-event-registration-form-response",
+  name: "New Event Registration Form Response",
+  description: "Emit new event when a fresh response is received on the event registration form. User needs to configure the prop of the specific event. [See the documentation](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/organizations/events?view=li-lms-2024-01&tabs=http)",
+  version: "0.0.3",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    app,
+    timer: {
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+      },
+    },
+    organizationId: {
+      propDefinition: [
+        app,
+        "organizationId",
+      ],
+    },
+    eventId: {
+      propDefinition: [
+        app,
+        "eventId",
+        ({ organizationId }) => ({
+          organizationId,
+        }),
+      ],
+    },
+  },
+  async run() {
+    const {
+      app,
+      organizationId,
+      eventId,
+    } = this;
+
+    const { elements } = await app.searchLeadFormResponses({
+      params: {
+        q: "owner",
+        owner: `(organization:${app.getOrganizationUrn(organizationId)})`,
+        leadType: "(leadType:EVENT)",
+        limitedToTestLeads: false,
+        associatedEntity: app.getEventUrn(eventId),
+      },
+    });
+
+    elements
+      .reverse()
+      .forEach((event) => {
+        this.$emit(event, {
+          id: event.id,
+          summary: `New Event Registration: ${event.id}`,
+          ts: event.submittedAt,
+        });
+      });
+  },
+};

package/sources/new-lead-gen-form-created/new-lead-gen-form-created.mjs

@@ -0,0 +1,68 @@
+import { DEFAULT_POLLING_SOURCE_TIMER_INTERVAL } from "@pipedream/platform";
+import app from "../../linkedin_ads.app.mjs";
+import sampleEmit from "./test-event.mjs";
+
+export default {
+  key: "linkedin_ads-new-lead-gen-form-created",
+  name: "New Lead Gen Form Created",
+  description: "Emit new event when a new lead is captured through a form. [See the documentation](https://learn.microsoft.com/en-us/linkedin/marketing/lead-sync/leadsync?view=li-lms-2023-07&tabs=http#find-lead-form-responses-by-owner)",
+  version: "0.0.2",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    app,
+    timer: {
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+      },
+    },
+    adAccountId: {
+      propDefinition: [
+        app,
+        "adAccountId",
+      ],
+    },
+    leadFormId: {
+      propDefinition: [
+        app,
+        "leadFormId",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+  },
+  async run() {
+    const {
+      app,
+      adAccountId,
+      leadFormId,
+    } = this;
+
+    const { versionId: leadFormVersionId } = await app.getLeadForm({
+      leadFormId,
+    });
+
+    const { elements } = await app.searchLeadFormResponses({
+      params: {
+        q: "owner",
+        owner: `(sponsoredAccount:${app.getSponsoredAccountUrn(adAccountId)})`,
+        leadType: "(leadType:SPONSORED)",
+        limitedToTestLeads: false,
+        versionedLeadGenFormUrn: app.getVersionedLeadGenFormUrn(leadFormId, leadFormVersionId),
+      },
+    });
+
+    elements
+      .reverse()
+      .forEach((event) => {
+        this.$emit(event, {
+          id: event.id,
+          summary: `New Lead Gen: ${event.id}`,
+          ts: event.submittedAt,
+        });
+      });
+  },
+  sampleEmit,
+};

package/sources/new-lead-gen-form-created/test-event.mjs

@@ -0,0 +1,48 @@
+export default {
+  "owner": {
+    "sponsoredAccount": "urn:li:sponsoredAccount:1232131"
+  },
+  "submitter": "urn:li:person:0",
+  "leadType": "SPONSORED",
+  "leadMetadata": {
+    "sponsoredLeadMetadata": {
+      "campaign": "urn:li:sponsoredCampaign:32131231"
+    }
+  },
+  "versionedLeadGenFormUrn": "urn:li:versionedLeadGenForm:(urn:li:leadGenForm:3213,1)",
+  "id": "52dcb737-26f9-4af3-b1fc-935b3e93f838-4",
+  "submittedAt": 1706741502694,
+  "testLead": true,
+  "associatedEntity": {
+    "associatedCreative": "urn:li:sponsoredCreative:369799186"
+  },
+  "formResponse": {
+    "consentResponses": [],
+    "answers": [
+      {
+        "answerDetails": {
+          "textQuestionAnswer": {
+            "answer": "test1@gmail.com"
+          }
+        },
+        "questionId": 20502584796
+      },
+      {
+        "answerDetails": {
+          "textQuestionAnswer": {
+            "answer": "Test 1"
+          }
+        },
+        "questionId": 20502643516
+      },
+      {
+        "answerDetails": {
+          "textQuestionAnswer": {
+            "answer": "Test 1"
+          }
+        },
+        "questionId": 20502667260
+      }
+    ]
+  }
+};