feat: add Pinterest click ID capture (epik/_epik) by jciafardone · Pull Request #1126 · mParticle/mparticle-web-sdk

jciafardone · 2025-12-06T01:43:26Z

Add Pinterest epik and _epik parameter mapping to integrationMappingExternal.

Added epik parameter mapping to capture Pinterest click IDs
Added _epik parameter mapping to capture Pinterest click IDs
Both map to Pinterest.click_id in custom flags
Supports capture from query parameters, cookies, and localStorage
Reference: https://developers.pinterest.com/docs/track-conversions/track-conversions-in-the-api/

Testing:

Added comprehensive tests covering both epik and _epik variants
Tests verify capture from all three sources (query params, cookies, localStorage)
Tests verify proper mapping to custom flags

Background

Pinterest uses both epik (query parameter) and _epik (cookie) to track click IDs
The epik parameter is appended by Pinterest to ad click URLs
The _epik cookie is stored by Pinterest's tag
Both variants need to be captured to ensure comprehensive click ID tracking
Pinterest requires the click ID to be sent as Pinterest.click_id custom flag for Pinterest Conversions API (CAPI) integration
Currently, the SDK captures click IDs for Facebook, Google, TikTok, and Snapchat, but not Pinterest
This change adds Pinterest to the list of supported integration-specific identifier captures

What Has Changed

Added epik parameter mapping to integrationMappingExternal in integrationCapture.ts
Added _epik parameter mapping to integrationMappingExternal in integrationCapture.ts
Both epik and _epik map to Pinterest.click_id custom flag
Each parameter variant is checked in all three sources:
- Query parameters (e.g., ?epik=value or ?_epik=value)
- Cookies (e.g., epik=value or _epik=value)
- localStorage (e.g., localStorage.getItem('epik') or localStorage.getItem('_epik'))
Follows standard priority resolution: query params > localStorage > cookies
Outputs to CUSTOM_FLAGS (consistent with other click ID integrations like gclid, fbclid, ttclid)
No processor function needed (unlike Facebook's fbclid which requires formatting)

Checklist

I have performed a self-review of my own code.
I have made corresponding changes to the documentation.
I have added tests that prove my fix is effective or that my feature works.
I have tested this locally.

Additional Notes

Tested extraction logic locally using standalone browser test file
Verified capture from URL query params, cookies, and localStorage for both epik and _epik variants
Confirmed priority resolution works correctly (query > localStorage > cookie)
Validated custom flag mapping to Pinterest.click_id
Verified that when both variants are present, both map to the same custom flag key
This change is additive and does not affect existing integrations
No breaking changes introduced

Add Pinterest _epik parameter mapping to integrationMappingExternal. - Maps _epik to Pinterest.click_id custom flag - Supports capture from URL query params, cookies, and localStorage - Follows standard priority: query params > localStorage > cookies - Outputs to CUSTOM_FLAGS (same as other click ID integrations) Reference: https://help.pinterest.com/en/business/article/add-event-codes Testing: - Verified extraction from URL, cookie, and localStorage sources - Confirmed priority resolution works correctly - Validated custom flag mapping to Pinterest.click_id

Co-authored-by: Alex S <49695018+alexs-mparticle@users.noreply.github.com>

- Add epik parameter mapping in addition to _epik - Both epik and _epik map to Pinterest.click_id custom flag - Support capture from query params, cookies, and localStorage - Add comprehensive tests for both parameter variants - Reference: https://developers.pinterest.com/docs/track-conversions/track-conversions-in-the-api/

rmi22186 · 2026-01-12T23:22:43Z

@jciafardone - looks like @alexs-mparticle 's comment here still hasn't been updated- 2dfa771#r2607709893

is his docs link correct? If so, please update.

rmi22186 · 2026-01-12T23:23:40Z

@jciafardone there's also some conflicts now, can you resolve, commit, and force push to this branch?

rmi22186

hit approve too soon. left one coment @jciafardone

added output for _epik

sonarqubecloud · 2026-01-16T23:24:34Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

rmi22186 · 2026-03-05T22:42:35Z

            });
        });
+
+        it('should map both epik and _epik to Pinterest.click_id', () => {


This test is failing. can you address? @jciafardone

Co-authored-by: Robert Ing <rmi22186@gmail.com>

…sert value is defined

sonarqubecloud · 2026-03-07T00:57:08Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

jciafardone · 2026-04-01T18:24:40Z

hi @rmi22186 , just wanted to circle back on this. Was there anything else I needed to do on this to be able to merge?

Stub epik in getQueryParams and expect Pinterest.click_id on events, matching the Snap integration test pattern.

cursor · 2026-05-14T18:11:12Z

PR Summary

Low Risk
Low risk, additive support for new Pinterest identifiers with explicit precedence rules and expanded test coverage; minimal chance of impacting existing integrations beyond the capture merge logic.

Overview
Adds Pinterest click ID support by capturing epik and _epik from query params, cookies, and localStorage and mapping both to the Pinterest.click_id custom flag.

Implements Pinterest precedence rules in IntegrationCapture.capture() (query params override localStorage/cookies; localStorage overrides cookies) and refactors/extends Jest and integration tests to cover the new IDs and the precedence behavior.

^{Reviewed by Cursor Bugbot for commit c5abf7d. Bugbot is set up for automated code reviews on this repo. Configure here.}

Extract expectCapturedSnapchatAndPinterestFlags helper to satisfy duplication threshold on new code.

- Add expectCapturedGoogleFacebookFlags helper - Remove duplicate commerce it blocks (identical copies)

- expectStubbedIntegrationCaptureFlags wraps Google/Facebook + Snap/Pinterest - Shared commerce purchase helpers and constants - logThreeEventsUploadAndParseBatch for batch upload tests

Replace duplicated event/pageview and commerce it() bodies with CAPTURE_CUSTOM_FLAG_CASES and COMMERCE_CAPTURE_CASES tables.

…stomFlags block - Fix indentation and close describe before partner identities suite - Use stable assertions (toBeDefined + includes) per review

Sonar rule javascript:S7764 prefers globalThis over window in tests; behavior unchanged under jsdom.

Satisfies Sonar no-zero-fraction rule; value unchanged.

A missing brace nested _scid under _epik and broke integrationMappingExternal parsing. Restore _scid as a top-level key next to Pinterest entries.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 84979c4. Configure here.}

Assert both Pinterest source keys are registered in filtered mappings, then that Pinterest.click_id is one of the input values (same key, last-write wins).

epik and _epik map to the same custom flag. Prefer query params over localStorage and cookies, then localStorage over cookies, mirroring Facebook fbclid/_fbc and Rokt-style precedence. Add Jest coverage for each tier.

Add clickIdsAfterFullCaptureAllMode helper; drive Pinterest, Snapchat, and Rokt #capture cases from tables; consolidate capture V2 mode gating tests.

… tests Restores Window augmentation typing for mParticle (fixes rollup TS2352). Sonar may flag window again; acceptable tradeoff.

sonarqubecloud · 2026-05-14T19:35:40Z

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

jciafardone changed the base branch from master to development December 8, 2025 17:56

rmi22186 force-pushed the development branch from c7458c7 to 2e7c07d Compare December 9, 2025 18:17

jciafardone added 2 commits December 9, 2025 14:07

test: add Pinterest _epik click ID tests

20e5c56

test: add Pinterest _epik tests for cookies and localStorage

6b060f0

rmi22186 force-pushed the development branch 3 times, most recently from a790359 to 0ba2d13 Compare December 10, 2025 15:31

alexs-mparticle reviewed Dec 10, 2025

View reviewed changes

Comment thread src/integrationCapture.ts Outdated

Comment thread src/integrationCapture.ts Outdated

rmi22186 force-pushed the development branch 2 times, most recently from 905641c to b16bdd2 Compare December 10, 2025 21:07

jciafardone and others added 2 commits December 17, 2025 13:22

Update src/integrationCapture.ts

e11cf61

Co-authored-by: Alex S <49695018+alexs-mparticle@users.noreply.github.com>

jciafardone requested a review from alexs-mparticle December 17, 2025 22:12

Merge branch 'development' into patch-1

0097412

jciafardone changed the title ~~feat(integration): add Pinterest _epik click ID capture~~ feat(integration): add Pinterest click ID capture (epik/_epik) Jan 13, 2026

Update integrationCapture.ts

fd32377

rmi22186 approved these changes Jan 16, 2026

View reviewed changes

rmi22186 reviewed Jan 16, 2026

View reviewed changes

Comment thread src/integrationCapture.ts

rmi22186 requested changes Jan 16, 2026

View reviewed changes

Update integrationCapture.ts

6f8b9f5

added output for _epik

jciafardone requested a review from rmi22186 January 16, 2026 23:28

rmi22186 reviewed Mar 5, 2026

View reviewed changes

Comment thread test/jest/integration-capture.spec.ts Outdated

rmi22186 reviewed Mar 5, 2026

View reviewed changes

jciafardone and others added 2 commits March 6, 2026 16:46

Apply suggestion from @rmi22186

f0da933

Co-authored-by: Robert Ing <rmi22186@gmail.com>

Fix epik/_epik Pinterest.click_id test: accept either key name and as…

db0f071

…sert value is defined

jciafardone requested a review from rmi22186 March 10, 2026 20:59

rmi22186 requested a review from a team as a code owner March 12, 2026 15:01

rmi22186 force-pushed the development branch from eb714c1 to fd9ab0f Compare March 12, 2026 20:01

test: assert Pinterest.click_id in integration capture suite

ec2971b

Stub epik in getQueryParams and expect Pinterest.click_id on events, matching the Snap integration test pattern.

jciafardone added 2 commits May 14, 2026 11:15

test: dedupe Snapchat/Pinterest custom flag assertions for Sonar

6e95191

Extract expectCapturedSnapchatAndPinterestFlags helper to satisfy duplication threshold on new code.

test: reduce Sonar duplication in integration capture suite

a2e669a

- Add expectCapturedGoogleFacebookFlags helper - Remove duplicate commerce it blocks (identical copies)

cursor Bot reviewed May 14, 2026

View reviewed changes

Comment thread src/integrationCapture.ts

Comment thread test/jest/integration-capture.spec.ts Outdated

jciafardone added 7 commits May 14, 2026 11:24

test: further dedupe integration capture suite for Sonar

59255fd

- expectStubbedIntegrationCaptureFlags wraps Google/Facebook + Snap/Pinterest - Shared commerce purchase helpers and constants - logThreeEventsUploadAndParseBatch for batch upload tests

test: data-driven integration capture cases for Sonar duplication

67e887a

Replace duplicated event/pageview and commerce it() bodies with CAPTURE_CUSTOM_FLAG_CASES and COMMERCE_CAPTURE_CASES tables.

fix(test): repair Pinterest epik/_epik Jest test and #getClickIdsAsCu…

4cc9fa8

…stomFlags block - Fix indentation and close describe before partner identities suite - Use stable assertions (toBeDefined + includes) per review

fix(test): use globalThis instead of window for Sonar

53288fd

Sonar rule javascript:S7764 prefers globalThis over window in tests; behavior unchanged under jsdom.

fix(test): drop redundant .0 from commerce Revenue literal

ad190b7

Satisfies Sonar no-zero-fraction rule; value unchanged.

fix(test): use globalThis in tests-integration-capture for Sonar

63f81ac

fix(integrationCapture): close _epik mapping before _scid

84979c4

A missing brace nested _scid under _epik and broke integrationMappingExternal parsing. Restore _scid as a top-level key next to Pinterest entries.

cursor Bot reviewed May 14, 2026

View reviewed changes

Comment thread src/integrationCapture.ts

jciafardone added 5 commits May 14, 2026 11:51

test(integration-capture): clarify epik/_epik custom flag collision test

ef32e83

Assert both Pinterest source keys are registered in filtered mappings, then that Pinterest.click_id is one of the input values (same key, last-write wins).

test(integration-capture): dedupe Jest setup for Sonar duplication

48c78fe

Add clickIdsAfterFullCaptureAllMode helper; drive Pinterest, Snapchat, and Rokt #capture cases from tables; consolidate capture V2 mode gating tests.

fix(test): drop redundant cast in clickIdsAfterFullCaptureAllMode

0e4f824

revert(test): use window instead of globalThis in integration capture…

c5abf7d

… tests Restores Window augmentation typing for mParticle (fixes rollup TS2352). Sonar may flag window again; acceptable tradeoff.

jciafardone changed the title ~~feat(integration): add Pinterest click ID capture (epik/_epik)~~ feat: add Pinterest click ID capture (epik/_epik) May 14, 2026

jciafardone closed this May 14, 2026

jciafardone deleted the patch-1 branch May 14, 2026 20:00

Uh oh!

Conversation

jciafardone commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

What Has Changed

Checklist

Additional Notes

Uh oh!

Uh oh!

Uh oh!

rmi22186 commented Jan 12, 2026

Uh oh!

rmi22186 commented Jan 12, 2026

Uh oh!

Uh oh!

rmi22186 left a comment

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Jan 16, 2026

Quality Gate passed

Uh oh!

Uh oh!

rmi22186 Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Mar 7, 2026

Quality Gate passed

Uh oh!

jciafardone commented Apr 1, 2026

Uh oh!

cursor Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud Bot commented May 14, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jciafardone commented Dec 6, 2025 •

edited

Loading

cursor Bot commented May 14, 2026 •

edited

Loading