Custom API Campaigns for Apps

Follow

Custom API campaigns let you use the power of Dynamic Yield A/B testing and automatic allocation, while fully controlling how the campaigns are rendered on your site. Variations of your custom API campaigns are JSON files, so each call results in a JSON that you can use to render an element on your site. 

Creating server-side API custom campaigns 

  1. Go to API Campaigns › Add New › Custom
  2. Enter a name, and add notes and labels (optional).
  3. Specify the API Selector. This selector is needed in API calls to the campaign. 
  4. Configure the targeting settings of the experience to determine when, where, and for whom the experience is displayed, and then click Next. 
  5. Create variations in JSON format using templates, or based on other experiences.
  6. When you are done with each variation, click Save Variation.
  7. Set the allocation, primary metric, and advanced experience settings.
  8. Configure how much of your traffic to allocate to each variation to the control group.
  9. Click the preview icon 24px__1_.svg to see how your variation will appear. 
  10. Click Save Experience. 
  11. Click the plus icon icon_plus3.png to create an additional targeted experience.
  12. Click Save and Publish when you are ready to go.
  13. Continue below with the procedures to call your campaign and track engagement. 

Calling a server-side custom campaign

In your code, you will use DYAP.choose() to request a variation of a campaign.  

Path 

https://dy-api.com/v2/serve/user/choose 

HTTP Method
  • POST

Headers
  • dy-api-key: Your API key
  • content-type: application/json

Body Parameters
  • user: The User ID. The type of ID to use differs between API-Only Mode and Web Mode. In API-Only Mode, you are responsible for generating IDs for new users, and persisting them for existing ones. In Web Mode a Dynamic Yield-generated identifier is used, and managed via cookies.
    • id: The customer-supplied User ID. Required in API-Only Mode: Not supported in Web Mode.
    • dyid: Required in Web Mode: If the _dyid cookie exists, pass its value here. Otherwise, in case both this parameter and dyid_server are not passed, a new user ID will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
    • dyid_server: Required in Web Mode: If the _dyid_server cookie exists, pass its value here. Not supported in API-Only Mode.
  • session: The Session ID. The type of identifier differs between API-Only Mode and Web Mode. In API-Only Mode, the identifier is for you to generate & persist. In Web Mode, a Dynamic Yield-generated identifier is used.
    • custom: Required in API-Only Mode: the customer-supplied session identifier. Not supported in Web Mode
    • dy: In Web Mode, pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
  • sessionId: Deprecated. In pre-release versions of the API, this parameter was used for passing customer-managed session IDs. Please use the session parameter instead.
  • selector:
    • names: Array of Dynamic Yield campaign names to choose variations for. Pass the API Selector Name of campaigns rather than the display name, which may change by the Admin UI User. Names are case-insensitive, but whitespace-sensitive. An empty list is valid.
    • preview: Preview token IDs, as passed by the dyApiPreview URL parameter on preview
      • ids: Array of preview tokens, as provided in the dyApiPreview URL parameter.
  • context: 
    • page: 
      • type: Page type, such as HOMEPAGE, CATEGORY, PRODUCT, etc.
      • data: Additional data related to the page type, such as the product SKU for PRODUCT-type pages.
      • location: Page URL (for web), location (for SPAs), or screen name (for mobile apps)
      • referer: Page referrer, if available. Optional.
      • locale: Page locale, such as "en_US". Optional.
    • Device:
      • userAgent: For web-based clients, the User-Agent string. If not passed, the API Gateway will check for that header in the HTTPS request. Optional.
      • ip: The client IP address, for geolocation-based targeting and audience building. If not passed, the IP of the caller is used. Optional.
    • pageAttributes: A shallow object of custom attributes that can be used for campaign targeting in the Admin UI. Optional.
  • Options:
    • isImplicitPageview: Set to false to disable implicit pageview reporting. Use this when calling choose more than once for a pageview. Boolean.
    • returnAnalyticsMetadata: Whether to return additional metadata (display names & IDs for all entities) useful for reporting to analytics tools. Boolean.

 

Node.JS Example


var request = require("request");

var options = {
  method: 'POST',
  url: 'https://dy-api.com/v2/serve/user/choose',
  headers: {'content-type': 'application/json', 'dy-api-key': 'your-api-key'},
  body: `{
  "selector": {
    "names": [
      "test1"
    ]
  },
  "user": {
    "id": "customUserId123"
  },
  "session": {
    "custom": "myCustomSession345"
  },
  "context": {
    "page": {
      "type": "HOMEPAGE",
      "location": "https://example.org",
      "locale": "en_US",
      "data":[]
    },
    "device": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
      "ip": "54.100.200.255"
    }
  },
  "options": {
    "isImplicitPageview": false,
    " returnAnalyticsMetadata": false
  }}`
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

For more details, see the API reference. 

Reporting Engagement

Report clicks on your campaigns to Dynamic Yield using the following API call:

Path 

https://dy-api.com/v2/collect/user/engagement 

HTTP Method
  • POST

Headers
  • dy-api-key: Your API key
  • content-type: application/json

Body Parameters
  • user: The User ID. The type of ID to use differs between API-Only Mode and Web Mode. In API-Only Mode, you are responsible for generating IDs for new users, and persisting them for existing ones. In Web Mode a Dynamic Yield-generated identifier is used, and managed via cookies.
    • id: The customer-supplied User ID. Required in API-Only Mode: Not supported in Web Mode.
    • dyid: Required in Web Mode: If the _dyid cookie exists, pass its value here. Otherwise, in case both this parameter and dyid_server are not passed, a new user ID will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
    • dyid_server: Required in Web Mode: If the _dyid_server cookie exists, pass its value here. Not supported in API-Only Mode.
  • session: The Session ID. The type of identifier differs between API-Only Mode and Web Mode. In API-Only Mode, the identifier is for you to generate & persist. In Web Mode, a Dynamic Yield-generated identifier is used.
    • custom: Required in API-Only Mode: the customer-supplied session identifier. Not supported in Web Mode
    • dy: Pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
  • Engagements: One or more engagements with a variation in an array
    • type: Set to CLICK for Custom Campaigns, or SLOT_CLICK for Recommendations 
    • decisionID: For a Custom Campaign, the unique Decision ID as returned from the choose endpoint. Not used for Recommendations.
    • variations: For a Custom Campaign, an array of one or more variation IDs the user interacted with, such as [45711, 49623]. Not used for Recommendations.
    • slotId: For a Recommendation Campaign, the Slot ID for the specific clicked item as returned from the choose endpoint.

For more details, see the API reference.  

Validating your implementation

Check out the API Logs to see a history of recent API calls, their status, and much more.