> For the complete documentation index, see [llms.txt](https://sdk-doc.tyrads.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdk-doc.tyrads.com/iframe/installation/nodejs.md). # NodeJS Integrate your NodeJS app with us using our NodeJS package ## Installation Add `@tyrads.com/tyrads-sdk-iframe` to your `package.json` as follows: ``` npm install --save @tyrads.com/tyrads-sdk-iframe # or yarn add @tyrads.com/tyrads-sdk-iframe ``` > The latest available version of NodeJS `@tyrads.com/tyrads-sdk-iframe` is [v0.2.2](https://github.com/tyrads-com/tyrads-node-sdk-iframe/releases/tag/v0.2.2). ## Get Started After successfully installing our package, create a TyrAdsSdk object with your API key and API secret: ```php const tyradsSDK = TyradsSDK.make(API_KEY, API_SECRET); ``` ### Localization This `TyrAdsSdk` class also supports localization, more info about [localization](/iframe/installation/manual-integration.md#localization) For example: ```php const tyradsSDK = TyradsSDK.make(API_KEY, API_SECRET, "en"); ``` ## Authentication You can do the authentication by calling to our package ```php const authResponse = await tyradsSDK.authenticate({ "PUBLISHER_USER_ID", // Publisher User ID }); ``` After obtaining the token successfully, you can call `iframeUrl` method to get the iframe URL ```php const iframeUrl = tyradsSDK.iframeUrl(authResponse.getToken()) // Result: https://sdk.tyrads.com?token=eyJ2YWwiOiI3M3NIeUpNQlp4QzA1TlRHVzhxRExhWWNTeUQ5TTJIT0h3NXBvL3djVVp1Z09MR20wOTJJOTRReDBuYUFLeXhmVGRCaGYra2gvVGcydWFlbUh6aWR6S00vTmV0SEtVZVlWNk5Pdkc5Wnd5bytkSkxmUnA0aWt2eE9yQ01YTXF6LzBnRmZ3RUpucHMxem95WnRkYkVlQXJQNER3cDRZVkttb1lBdEIrZlB6cFZ3R25SSEE5UjROa2U2cGJTeTJod2c2UmI3UnN0QzZiN2Y2cENBYTlqaEhvQXhtdjM5UERPU2tDdWpHMmJIQ2N1cVRldVQ4a3hDSEE9PSIsInZlYyI6InNWbzZrejZRa09iS0tDeDUiLCJ0YWciOiJ1eDNnbjEwNEdUWXpvV1J2TTZVck1BPT0ifQ== ``` {% hint style="info" %} 1. A new token must be requested each time a user wants to access the offerwall. 2. Each token is valid for **7 days** only {% endhint %} ### Deeplinking Routes This `iframeUrl` method also supports deeplinking, more info about [deeplinking routes](/iframe/installation/manual-integration.md#deeplinking-routes) For example: ```php const iframeUrl = tyradsSDK.iframeUrl(authResponse.getToken(), "/settings/language") // Result: https://sdk.tyrads.com?to=/settings/language&token=eyJ2YWwiOiI3M3NIeUpNQlp4QzA1TlRHVzhxRExhWWNTeUQ5TTJIT0h3NXBvL3djVVp1Z09MR20wOTJJOTRReDBuYUFLeXhmVGRCaGYra2gvVGcydWFlbUh6aWR6S00vTmV0SEtVZVlWNk5Pdkc5Wnd5bytkSkxmUnA0aWt2eE9yQ01YTXF6LzBnRmZ3RUpucHMxem95WnRkYkVlQXJQNER3cDRZVkttb1lBdEIrZlB6cFZ3R25SSEE5UjROa2U2cGJTeTJod2c2UmI3UnN0QzZiN2Y2cENBYTlqaEhvQXhtdjM5UERPU2tDdWpHMmJIQ2N1cVRldVQ4a3hDSEE9PSIsInZlYyI6InNWbzZrejZRa09iS0tDeDUiLCJ0YWciOiJ1eDNnbjEwNEdUWXpvV1J2TTZVck1BPT0ifQ== ``` ### Embedding The Iframe If your website is using html, you can add an iframe to your page to integrate TyrAds web: ```html ``` For example: ```html ``` ## Media Source Data Sending The authenticate method accepts additional user attributes for UTM/media-source attribution. Example request payload: ``` { "publisherUserId": "sdk-test-full-string-ug-mqo0680t", "age": 28, "gender": 1, "email": "tester@example.com", "phoneNumber": "+14155550123", "sub1": "sub1-value", "sub2": "sub2-value", "sub3": "sub3-value", "sub4": "sub4-value", "sub5": "sub5-value", "userGroup": "{\"promo_affinity_ratio\":0.42,\"dynamic_payer_segment\":\"NonPayer\",\"activity_segment\":\"Tier 3\",\"seniority_segment\":\"Tier 4\",\"rewarded_video_watcher_category\":\"High\"}", "mediaSourceName": "facebook", "mediaSourceId": "fb-001", "mediaSubSourceId": "fb-sub-001", "incentivized": true, "mediaAdsetName": "spring-campaign", "mediaAdsetId": "adset-123", "mediaCreativeName": "banner-a", "mediaCreativeId": "creative-456", "mediaCampaignName": "q2-promo", "engagementId": 987654 } ``` **Attributes Table** | Parameter | Type | Description/ Formatting | | ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `publisherUserId` | String | Specific identifier of a user for conversion tracking | | `age` | Int | User's age (e.g. `"1-99"` | | `gender` | Int | User's gender (e.g. `"1-Male", "2-Female"` | | `email` | String | User's email address | | `phoneNumber` | String | User's phone number. Prefix `+` must be replaced with `00` (e.g. `0015555551234`) | | `sub1` to `sub5` | String | Custom parameters for publisher tracking | | `userGroup` | JSON String |

Segment identifier passed as a JSON string (a stringified JSON object, not a raw JSON object).
\[e.g. "{"promo\_affinity\_ratio":0.42,"dynamic\_payer\_segment":"NonPayer","activity\_segment":"Tier 3","seniority\_segment":"Tier 4","rewarded\_video\_watcher\_category":"High"}"]

\*\*Can be any usergroup data that you would want to pass.

| | `mediaSourceName` | l | Platform of acquisition (e.g. `"Facebook"`, `"Google"`) | | `mediaSourceId` | String | Unique ID representing the media source | | `mediaSubSourceId` | String | Sub-source ID | | `incentivized` | Boolean | If the acquisition was via incentivized networks | | `mediaAdsetName` | String | Acquisition ad set name | | `mediaAdsetId` | String | Acquisition ad set ID | | `mediaCreativeName` | String | Acquisition ad creative asset name | | `mediaCreativeId` | String | Acquisition ad creative asset ID | | `mediaCampaignName` | String | Associated ad campaign name | | `engagementId` | Int | Optional engagement identifier to associate SDK activity with specific user engagements or campaigns | ## Implementation of Placement ID The placementId identifies the specific placement (ad unit) that the offerwall or widget is opened from, allowing you to track and configure performance per placement. Pass it as an argument to the iframeUrl or iframePremiumWidget methods, and the SDK appends it to the generated URL as a placementId query parameter. The optional second argument lets you deeplink to a specific route (for iframeUrl) or specify a widget name (for iframePremiumWidget). The examples below show the method calls and their resulting URLs: ``` // iframeUrl(token, null, 123) https://v4.sdk.tyrads.com?token=demo.jwt.token&placementId=123 // iframeUrl(token, "/offers/3454", 123) https://v4.sdk.tyrads.com?token=demo.jwt.token&to=%2Foffers%2F3454&placementId=123 // iframePremiumWidget(token, null, 123) https://v4.sdk.tyrads.com/widget?token=demo.jwt.token&placementId=123 // iframePremiumWidget(token, "rewards", 123) https://v4.sdk.tyrads.com/widget?token=demo.jwt.token&name=rewards-widget&placementId=123 ``` ## Example For example implementation using our NodeJS SDK, you can find it here {% embed url="" %}