Investec Platform Plugins

Appearance

Personalisation ​

@investec/plugins-personalisation wraps the Adobe Target personalisation endpoints used by the platform and provides helpers for generating profile-update payloads from returned content cards.

Package ​

Warning: By default, this package must be installed only by the platform team into the Investec Online shell application. Direct installation into a feature application is not permitted unless the Web Platform team has granted an explicit integration contract for that specific use — treat this as a rare, approved exception, not the norm. Consumers should otherwise use this plugin's behaviour through the Invsy SDK, or contribute a bounded, governed change to this plugin's own source (see Plugin change governance).

sh
npm install --save @investec/plugins-personalisation

The platform owns installation of released plugin versions. A consuming team normally contributes shared personalisation logic in this repository and then asks the platform team to adopt the published version.

Public contract ​

The main package-root exports include:

  • personalisation.activeEnvironment
  • getAdobeTargetDataByTemplate(authRes, payload)
  • postProfileUpdatesByTemplate(template)
  • postProfileUpdatesOnCallToAction(card, callToActionType)
  • mapping helpers such as buildProfileMapByTemplate(...), buildProfileMapByCallToAction(...), combineProfileUpdates(...), sanitizeStringForProfile(...), and validateCardStructureForProfileAnalytics(...)

Integration pattern ​

ts
import { getAdobeTargetDataByTemplate, personalisation, postProfileUpdatesOnCallToAction } from '@investec/plugins-personalisation';

personalisation.activeEnvironment = 'staging';

const response = await getAdobeTargetDataByTemplate(authResponse, {
  Templates: ['Pulsator_Template'],
});

await postProfileUpdatesOnCallToAction(card, 'primary');

Template retrieval ​

getAdobeTargetDataByTemplate(...) posts to:

text
/edge/personalisation/api/v1/target/personalisation

It requires a payload containing a non-empty Templates array.

Profile update helpers ​

The package supports two update flows:

  • impression/template-level updates through postProfileUpdatesByTemplate(...)
  • CTA engagement updates through postProfileUpdatesOnCallToAction(...)

Both methods derive profile attributes from Adobe Target response data and post them to:

text
/edge/personalisation/api/v1/target/profile-update

How consumers extend it ​

Consumers usually extend this package by controlling:

  • which template names are requested;
  • when a returned card should trigger a profile update;
  • whether to inspect or test the generated profile map before posting it.

The mapping helpers make that easier without changing the shared package.

Change the package when the Adobe Target response contract, endpoint contract, or shared profile-mapping rules need to change.

Extension example: inspect the generated CTA profile update before posting ​

ts
import { buildProfileMapByCallToAction, postProfileUpdatesOnCallToAction, type IRefinedMbox } from '@investec/plugins-personalisation';

export async function trackPrimaryOfferClick(card: IRefinedMbox) {
  const previewProfileMap = buildProfileMapByCallToAction(card, 'primary');

  console.log('Profile update payload preview:', previewProfileMap);

  const posted = await postProfileUpdatesOnCallToAction(card, 'primary');

  if (!posted) {
    console.warn('Profile update failed');
  }
}

Extend the shared plugin ​

Use:

  • personalisation.ts for approved Target API calls and reusable mapping logic;
  • environment.ts for environment-specific endpoint or capability values;
  • types/adobe-target.interface.ts for request, response, card, template, and profile-map types;
  • src/index.ts for supported public exports.

For an API addition, preserve the WPaaS: critical requirement where approved, validate required inputs, return explicit failure behaviour, and add tests for malformed cards, empty updates, HTTP failure, and environment selection.

Contact the Web Platform team and personalisation owner before changing Adobe Target profile naming, audience-management behaviour, customer attributes, endpoint ownership, or the meaning of impression and engagement updates.

Consumer notes ​

  • The current implementation accepts authRes in getAdobeTargetDataByTemplate(...), but uses only the configured endpoint and request payload.
  • postProfileUpdatesByTemplate(...) and postProfileUpdatesOnCallToAction(...) return false on failure rather than throwing.
  • The mapping helpers are useful when the consumer needs to inspect or test the exact profile payload before posting it.