Audience Segment External Feed Methods

Those are the routes to implement for an Audience Segment External Feed plugin.

Generic

Those are the mandatory methods to implement.

instanceContextBuilder

This method

• validates feed properties and selected identifying resources.

• simplifies the instance handling by managing in one place properties, credentials, configurations, api clients...

It is called once at the beginning of the feed instantiation. It may be called again in the 3 other generic methods: onExternalSegmentCreation, onExternalSegmentConnection and onUserSegmentUpdate if we want to refresh the instance context.

We have to define a custom interface for this extended context, so we can return whatever we want in it.

instanceContextBuilder(feedId: string): Promise<InstanceContext>

Input parameters

There is only one input parameter feedId.

feedId (string, required):

Return

This method returns a context of type AudienceFeedConnectorBaseInstanceContext or an extended context of type InstanceContext. We recommend you to use the extended context in order to simplify the reuse of objects and variables in the plugin code.

The original context format contains the feed metadata and its properties.

ctx (AudienceFeedConnectorBaseInstanceContext)

The original format of the AudienceFeedConnectorBaseInstanceContext type is

Parameter	Type	Description
feed	AudienceSegmentExternalFeedResource	Represents the external feed resource for the audience segment.
feedProperties	PropertiesWrapper	Wrapper for properties associated with the feed, containing metadata and configurations.

With the object feed (AudienceSegmentExternalFeedResource) that represents the external feed resource for the audience segment:

Parameter	Type	Description
id	string	Unique identifier for the audience segment external feed.
plugin_id	string	Identifier for the plugin associated with the feed.
organisation_id	string	Identifier for the organization that owns the feed.
group_id	string	Identifier for the group to which the feed belongs.
artifact_id	string	Identifier for the specific plugin artifact related to the feed.
version_id	string	Version identifier for the feed, indicating its versioning.
selected_identifying_resources	IdentifyingResourceShape optional	Optional array of identifying resources used for segment identification.
created_by	string	Optional identifier for the user that created the feed.

The extended context contains the feed metadata, the feed properties, plus a bunch of useful variables and objects.

instanceContext (InstanceContext)

export interface InstanceContext extends AudienceFeedConnectorBaseInstanceContext

Those are the variables and objects that extend the original context (AudienceFeedConnectorBaseInstanceContext).

Parameter	Type	Description
technicalConfig	TechnicalConfiguration	Configuration details for technical aspects.
loggerPrefix	string	A prefix for logging to identify the source of log messages.
segment	AudienceSegmentResource	The audience segment resource being processed.
properties	Properties	Plugin properties of the created feed.
credentials	Credentials	Credentials for external systems.
datamartConfig	DatamartConfiguration	Configuration specific to the datamart.
micsApiClient	MicsApiClient	Client for interacting with the MICS API.
partnerClient	PartnerClient	Client for interacting with the partner solution.

Code

There is only one input parameter feedId, but you must retrieve the context ctx at the beginning of the method code to extend it, like this:

const ctx = await super.instanceContextBuilder(feedId);

Code example

export interface InstanceContext extends AudienceFeedConnectorBaseInstanceContext {
  technicalConfig: TechnicalConfiguration;
  loggerPrefix: string;
  segment: AudienceSegmentResource;
  properties: Properties;
  credentials: Credentials;
  datamartConfig: DatamartConfiguration;
  datamartCountryMapping?: DatamartCountryMapping;
  micsApiClient: MicsApiClient;
  linkedinClient: LinkedInClient;
}

protected async instanceContextBuilder(feedId: string): Promise<InstanceContext> {
  const ctx = await super.instanceContextBuilder(feedId);
  const segment: AudienceSegmentResource = await this.fetchAudienceSegment(feedId);
  const loggerPrefix = `Segment: ${segment.id} - Feed: ${feedId} - Datamart: ${segment.datamart_id}`;

  try {
    const { credentials, technicalConfig, datamartConfig, datamartCountryMapping } =
      await this.retrieveConfigurationsFiles({
        ctx,
        segment,
        loggerPrefix,
      });

    const partnerAccountId = this.findStringProperty<string>({
      findStringProperty: ctx.feedProperties.findStringProperty,
      name: PluginProperties.PARTNER_ACCCOUNT_ID,
      required: this.IS_MANDATORY,
    });

    if (!partnerAccountId) {
      throw new Error(`${PluginProperties.PARTNER_ACCCOUNT_ID} is mandatory, but not found`);
    }

    const segmentName =
      this.findStringProperty<string | undefined>({
        findStringProperty: ctx.feedProperties.findStringProperty,
        name: PluginProperties.SEGMENT_NAME,
        required: this.NOT_MANDATORY,
      }) || segment.name;

    const partnerSegmentId = this.findStringProperty<string | undefined>({
      findStringProperty: ctx.feedProperties.findStringProperty,
      name: PluginProperties.PARTNER_SEGMENT_ID,
      required: this.NOT_MANDATORY,
    });

    const properties = {
      partnerAccountId,
      segmentName,
      partnerSegmentId,
    };

    const selectedIdentifyingResources = ctx.feed.selected_identifying_resources;

    if (!selectedIdentifyingResources || !selectedIdentifyingResources.length) {
      throw new Error('No Identifying Resource found');
    }

    const micsApiClient = MicsApiClient.getInstance({
      apiToken: credentials.mics_api_token,
      loggerPrefix,
      logger: this.logger,
    });

    const partnerClient = new PartnerClient({
      credentials,
      partnerApiVersion: technicalConfig.partner_api_version,
      partnerEndpoint: technicalConfig.partner_endpoint,
      loggerPrefix,
      logger: this.logger,
    });

    this.logger.debug(`${loggerPrefix} - Instance Context set up for segment ${segment.id}.`);

    const customCtx = {
      ...ctx,
      technicalConfig,
      loggerPrefix,
      segment,
      properties,
      credentials,
      datamartConfig,
      datamartCountryMapping,
      micsApiClient,
      linkedinClient,
    };

    return customCtx;
  } catch (err) {
    this.logger.error(`${loggerPrefix} - instanceContextBuilder -- an error occured: ${(err as Error).message}`);
    throw err;
  }
}

onExternalSegmentCreation

This method checks wether the audience already exist on the partner platform, or if it must create it. In this last case, we create the audience.

Also, through the instance context method, this onExternalSegmentCreation method validates again the feed properties and selected identifying resources.

This method is called synchronously.

onExternalSegmentCreation(request: ExternalSegmentCreationRequest, ctx: InstanceContext): promise<ExternalSegmentCreationPluginResponse>

Input parameters

request (ExternalSegmentCreationRequest, required): An object containing the details necessary for creating the segment. It is sent by the platform at the feed creation.

request object format:

Parameter	Type	Description
feed_id	string	The unique identifier of the feed
segment_id	string	The unique identifier of the segment related to the feed
datamart_id	string	The identifier for the datamart of the segment

context (InstanceContext, required): The context in which the feed creation is executed, containing various configuration and resource objects.

Check the instance context section to understand the format of the feed instance context. You can find the extended context interface in the returns tab.

Return

Resolves to an object containing the status of the segment creation process, along with an optional message and visibility.

Promise<ExternalSegmentCreationPluginResponse>

ExternalSegmentCreationPluginResponse object format:

Parameter	Type
status	enum['ok' | 'error' | 'retry' | 'no_eligible_identifier']
message	string
visibility	enum['PRIVATE' | 'PUBLIC']

Code

Code example

// Trigger by the creation of a feed instance
protected async onExternalSegmentCreation(
    _: ExternalSegmentCreationRequest,
    ctx: InstanceContext,
  ): Promise<ExternalSegmentCreationPluginResponse> {
    this.logger.debug(`${ctx.loggerPrefix} - onExternalSegmentCreation step`);

    try {
      if ( !hasIdentifyingResource(ctx) ) {
        throw new Error(
          `Your User Profiles do not contain enough information for Linkedin connector to rely on them alone. Either an ID (mobile id or hashed email) OR the couple first and last name are required. Please contact your account manager.`,
        );
      }

      if (ctx.feedProperties.partnerSegmentId) {
        return await knownPartnerSegmentIdWorkflow({
          partnerSegmentId: ctx.feedProperties.partnerSegmentId,
          ctx,
          logger: this.logger,
        });
      }

      return unknownPartnerSegmentIdWorkflow({ ctx, logger: this.logger });
    } catch (err) {
      this.logger.error(`${ctx.loggerPrefix} - onExternalSegmentCreation - something went wrong:`, err);
      return {
        status: 'error',
        message: (err as Error).message,
        visibility: 'PUBLIC',
      };
    }
  }

onExternalSegmentConnection

Establishing connection with segment on destination platform.

This method check the availability of the segment on the destination platform.

Also, through the instance context method, this onExternalSegmentConnection method may validate feed properties and selected identifying resources. It is not mandatory at this step as it was supposed to be done beforehand.

onExternalSegmentConnection(request: ExternalSegmentConnectionRequest, context: InstanceContext): promise<ExternalSegmentCreationPluginResponse>

Input parameters

request (ExternalSegmentConnectionRequest, required): An object containing the details necessary for creating the segment. It is sent by the platform at the feed creation.

request object format:

Variable	Type	Description
feed_id	string	The unique identifier of the feed
segment_id	string	The unique identifier of the segment related to the feed
datamart_id	string	The identifier for the datamart of the segment

context (InstanceContext, required): The context in which the feed creation is executed, containing various configuration and resource objects.

Check the instance context section to understand the format of the feed instance context. You can find the extended context interface in the returns tab.

Return

Resolves to an object containing the status of the segment creation process, along with an optional message and visibility.

Promise<ExternalSegmentCreationPluginResponse>

ExternalSegmentCreationPluginResponse object format:

Variable	Type
status	enum['ok' | 'error' | 'retry' | 'no_eligible_identifier']
message	string
visibility	enum['PRIVATE' | 'PUBLIC'] optional

Code

Code example

protected async onExternalSegmentConnection(
    _: ExternalSegmentConnectionRequest,
    ctx: InstanceContext,
  ): Promise<ExternalSegmentConnectionPluginResponse> {
    this.logger.debug(`${ctx.loggerPrefix} - onExternalSegmentConnection step.`);

    try {
      if (!ctx.properties.partnerSegmentId) {
        throw new Error(`partnerSegmentId property is undefined while it should be by now`);
      }

      const partnerSegmentInfos = await ctx.partnerApiClient.fetchDMPSegment(ctx.properties.partnerSegmentId);

      this.logger.debug(
        `${ctx.loggerPrefix} - onExternalSegmentCreation - The partner segment Id (${ctx.properties.partnerSegmentId}) was retrieved: `,
        linkedinSegmentInfos,
      );

      return Promise.resolve({ status: 'ok' });
    } catch (err) {
      if ((err as CustomError).statusCode === 404) {
        return {
          status: 'external_segment_not_ready_yet',
          message: 'partner segment is not ready yet',
        };
      }
      this.logger.error(`${ctx.loggerPrefix} - onExternalSegmentConnection: something went wrong: `, err);
      return {
        status: 'error',
        message: (err as Error).message,
      };
    }
}

onUserSegmentUpdate

This method sends the user identifiers (insertion or deletion) or prepares the payload to be sent to the partner platform.

Depending on the plugin output type, this method will have different roles and return different objects.

• Single API calls (classic plugin)

  This method sends the user identifiers (insertion or deletion) to the partner platform.

• Batch API calls

  This method inserts the user identifiers in the batch through the returned object - it can be for both insertion or deletion.

  The batch will be sent to the partner platform through the onBatchUpdate method.

• File delivery

  This method inserts the user identifiers in the file through the returned object - it can be for both insertion or deletion.

Also, through the instance context method, this onUserSegmentUpdate method may again validate feed properties and selected identifying resources. It is not mandatory at this step again as it was supposed to be done beforehand.

onUserSegmentUpdate(request: UserSegmentUpdateRequest, context: InstanceContext): promise<BatchedUserSegmentUpdatePluginResponse<Payload>>

Input parameters

request (UserSegmentUpdateRequest, required): An object containing the details necessary for creating the segment. It is sent by the platform at the feed creation.

request object format:

Parameter	Type	Description
feed_id	string	unique identifier for the feed associated with the user segment update
session_id	string	identifier for the session during which the update is being made
datamart_id	string	identifier for the datamart where the user segment resides
segment_id	string	unique identifier for the segment being updated
user_identifiers	UserIdentifierInfo[]	array of user identifiers from the segment to send to the partner platform
user_profiles	UserProfileInfo[]	array of user profiles from the segment to send to the partner platform
ts	number	timestamp indicating when the update request was created
operation	UpdateType	type of update operation being performed, indicating whether it is an add, remove, or modify operation

context (InstanceContext, required): The context in which the feed creation is executed, containing various configuration and resource objects.

Check the instance context section to understand the format of the feed instance context. You can find the extended context interface in the returns tab.

Return (batch case)

Resolves to an object containing the batch of users identifiers to update on the segment destination platform.

Promise<BatchedUserSegmentUpdatePluginResponse<Payload>>

BatchedUserSegmentUpdatePluginResponse<Payload> object format:

Parameter	Type	Description
status	enum['ok' | 'error' | 'retry' | 'no_eligible_identifier']
data	UserSegmentUpdatePluginBatchDeliveryResponseData<Payload>[], optional
stats	UserSegmentUpdatePluginResponseStats[], optional
message	string, optional
next_msg_delay_in_ms	number, optional

Code

Code example (batch case)

protected async onUserSegmentUpdate(
    request: UserSegmentUpdateRequest,
    ctx: InstanceContext,
  ): Promise<BatchedUserSegmentUpdatePluginResponse<Payload>> {
    this.logger.debug(`${ctx.loggerPrefix} - onUserSegmentUpdate step.`);

    try {
      const payloads = await buildPayload({ ctx, request, logger: this.logger });

      if (!payloads) {
        if (this.logger.level === 'debug') {
          this.logger.warn(`No elements available for Batch Delivery for request ${JSON.stringify(request)}.`);
        }
        return Promise.resolve({ status: 'ok' });
      }

      return Promise.resolve({
        status: 'ok',
        data: payloads.map((payload) => {
          return {
            type: 'BATCH_DELIVERY',
            grouping_key: `${ctx.segment.id}_${ctx.feed.id}`,
            content: payload,
          };
        }),
      });
    } catch (err) {
      this.logger.error(`${ctx.loggerPrefix} - onUserSegmentUpdate: something went wrong: `, err);
      return {
        status: 'error',
        message: (err as Error).message,
      };
    }
  }

onTroubleshoot

This method is utilized to troubleshoot the feed using audience data from the partner platform.

onTroubleshoot(request: TroubleshootActionFetchDestinationAudience, ctx: InstanceContext): promise<ExternalSegmentTroubleshootResponse>

Input parameters

request (TroubleshootActionFetchDestinationAudience, required): An object containing the details necessary for handling the troubleshoot.

Parameter	Type	Description
feed_id	string	The unique identifier of the feed
segment_id	string	The unique identifier of the segment related to the feed
datamart_id	string	The identifier for the datamart of the segment
action	enum['FETCH_DESTINATION_AUDIENCE']

context (InstanceContext, required): The context in which the feed creation is executed, containing various configuration and resource objects.

Check the instance context section to understand the format of the feed instance context. You can find the extended context interface in the returns tab.

Return

Resolves to an object containing the status of the segment creation process, along with an optional message and visibility.

Promise<ExternalSegmentCreationPluginResponse>

ExternalSegmentCreationPluginResponse object format:

Parameter	Type	Description
status	enum['ok' | 'error' | 'retry' | 'no_eligible_identifier']
message	string
data	any, optional	Data to be displayed in the troubleshooting section of the feed card. It must provide as much data as possible to compare identifiers received, stored and used by the partner platform

Code

Code example

protected async onTroubleshoot(
    request: TroubleshootActionFetchDestinationAudience,
    ctx: InstanceContext,
  ): Promise<ExternalSegmentTroubleshootResponse> {
    if (request.action === 'FETCH_DESTINATION_AUDIENCE') {
      if (!ctx.properties.partnerSegmentId) {
        throw new Error(`partnerSegmentId property is undefined while it should be by now`);
      }

      const partnerSegmentInfos = await ctx.partnerClient.fetchDMPSegment(ctx.properties.partnerSegmentId);

      const troubleshootData = {
        matchedRate: this.computeMatchRate(partnerSegmentInfos),
        audienceInfos: partnerSegmentInfos,
      };

      return {
        status: 'ok',
        message: 'Here is the destination audience!',
        data: troubleshootData,
      };
    }

    return { status: 'not_implemented' };
  }

Batching

This method is required if we batch the calls to the partner API or to send a flat file.

onBatchUpdate

Send the batched payload of user identifiers to the partner platform.

This payload is prepared by our platform thanks to the unitary calls to the onUserSegmentUpdate method.

onBatchUpdate(request: BatchUpdateRequest<AudienceFeedBatchContext, T>, ctx: instanceContext): Promise<BatchUpdatePluginResponse>

Input parameters

request (BatchUpdateRequest<AudienceFeedBatchContext, Payload>)

Parameter	Type	Description
batch_content	T[]	Array of items (insertion/deletion) to be sent to the partner platform
ts	number	Timestamp indicating when the batch update request was created
context	AudienceFeedBatchContext	Context information relevant to the batch update process We do not use this variable from this parameter.

context (InstanceContext, required): The context in which the feed creation is executed, containing various configuration and resource objects.

Check the instance context section to understand the format of the feed instance context. You can find the extended context interface in the returns tab.

Return

Resolves to an object containing the status of the users identifiers sent to the destination platform, along with an optional message.

Promise<BatchUpdatePluginResponse>

BatchUpdatePluginResponse object format:

Parameter	Type
status	enum['OK' | 'ERROR' | 'RETRY']
message	string, optional
next_msg_delay_in_ms	number, optional
sent_items_in_success	number
sent_items_in_error	number

Code

Code example

protected async onBatchUpdate(
  request: BatchUpdateRequest<AudienceFeedBatchContext, Payload>,
  ctx: InstanceContext,
): Promise<BatchUpdatePluginResponse> {
  this.logger.debug(`${ctx.loggerPrefix} - onBatchUpdate - starting.`);

  try {
    if (!ctx.properties.partnerSegmentId) {
      throw new Error(`partnerSegmentId property is undefined while it should be by now`);
    }

    if (!request.batch_content.length) {
      this.logger.debug(`${ctx.loggerPrefix} - onBatchUpdate - Empty batch content. Returning`);
      return {
        status: 'OK',
        sent_items_in_success: 0,
        sent_items_in_error: 0,
      };
    }

    // SendPayloads is a function that sends the batched users to the partner platform.
    const updateStats = await ctx.partnerClient.SendPayload({
      partnerSegmentId: ctx.properties.partnerSegmentId,
      payload: request.batch_content,
    });

    this.logger.debug(
      `${ctx.loggerPrefix} - onBatchUpdate - total sent users: ${updateStats.total} / success: ${updateStats.successful} / errors: ${updateStats.errors} / errors details: `,
      { errorDetails: updateStats.messages },
    );

    return Promise.resolve({
      status: 'OK',
      sent_items_in_success: updateStats.successful,
      sent_items_in_error: updateStats.errors,
    });
  } catch (err) {
    this.logger.error(`${ctx.loggerPrefix} - onBatchUpdate - something went wrong:`, err);
    return {
      status: 'ERROR',
      message: (err as Error).message,
      sent_items_in_success: 0,
      sent_items_in_error: request.batch_content.length,
    };
  }
}

Destinations & Authentication (SDK v0.41.0+)

If your plugin version is configured with an authentication type, the SDK automatically fetches the destination credentials from the vault and passes them as an optional second argument to instanceContextBuilder. The same credentials are forwarded to onUserSegmentUpdate, onTroubleshoot, and onDynamicPropertyValuesQuery. See Destinations & Authentication for the full documentation on authentication methods and the destination model.

Dynamic properties

onDynamicPropertyValuesQuery

Enable the feed creation form to dynamically suggest values from the partner solution, allowing users to select from these options. Additionally, one dynamic property may depend on another.

onDynamicPropertyValuesQuery(request: ExternalSegmentDynamicPropertyValuesQueryRequest): promise<Response>

Input parameters

request (ExternalSegmentDynamicPropertyValuesQueryRequest): Request coming from the feed creation form.

Parameter	Type	Description
segment_id	string, optional	Optional identifier for the segment related to the feed being created
datamart_id	string	Identifier for the datamart associated with the feed being created
user_id	string	Unique identifier for the user making the query
properties	PluginProperty[], optional	Optional array of properties already set in the feed creation form

To better understand the properties array, here is an example type that can be found within it:

Parameter	Type
property_type	enum['STRING', 'URL', ...]
value	object[] value (string, optional) id (string, optional) ... depending on the property type

Return

Resolves to an object containing the array of the dynamic properties and their values to be displayed in the feed creation form.

Promise<ExternalSegmentDynamicPropertyValuesQueryResponse>

Parameter	Type	Description
status	enum['ok' | 'error' | 'not_implemented']	status of the dynamic property values query indicating whether the operation was successful, encountered an error, or is not implemented
message	string, optional	Optional message providing additional information about the query status
data	object[], optional	Optional array of objects containing the dynamic property values

Object format for each dynamic property present in the data array:

Parameter	Type	Description
property_technical_name	string
enum	object[]	Array of objects representing the possible values for the property

Object format for each value present in the enum array:

Parameter	Type	Description
label	string	Human-readable label for the property value displayed in the dropdown
value	string	Actual value associated with the property (technical most of the time)

Code

Code example

protected async onDynamicPropertyValuesQuery(
  request: ExternalSegmentDynamicPropertyValuesQueryRequest,
): Promise<ExternalSegmentDynamicPropertyValuesQueryResponse> {
  this.logger.info(
    `onDynamicPropertyValuesQuery - User: ${request.user_id} (Datamart: ${request.datamart_id}) requested the dynamic properties: `,
    request.properties,
  );

  try {
    const partnerAccountIdStrProps = request.properties?.find(
      (property) =>
        property.technical_name === (PluginProperties.PARTNER_ACCCOUNT_ID as string) &&
        property.property_type === 'STRING',
    ) as StringProperty | undefined;

    const partnerAccountId = partnerAccountIdStrProps?.value?.value;

    if (!partnerAccountId) {
      const partnerAccountsList = await this.retrievePartnerAccountsList(request);

      return {
        status: 'ok',
        message: `Successfully retrieved ${partnerAccountsList.length} partner accounts for user ${request.user_id}.`,
        data: [
          {
            property_technical_name: PluginProperties.PARTNER_ACCCOUNT_ID,
            enum: partnerAccountsList,
          },
        ],
      };
    }

    const partnerAccountsList = await this.retrievePartnerAccountsList(request, partnerAccountId);
    const segmentsList = await this.retrieveExistingSegments(request, partnerAccountId);

    return {
      status: 'ok',
      message: `Successfully retrieved ${segmentsList.length} segments for partner account: ${partnerAccountId}.`,
      data: [
        {
          property_technical_name: PluginProperties.PARTNER_ACCCOUNT_ID,
          enum: partnerAccountsList,
        },
        {
          property_technical_name: PluginProperties.PARTNER_SEGMENT_ID,
          enum: segmentsList,
        },
      ],
    };
  } catch (err) {
    const errorBody = (err as RequestError).response?.body;
    this.logger.error(`onDynamicPropertyValuesQuery - something went wrong:`, { ...err, errorBody });
    return {
      status: 'error',
      message: (err as Error).message,
    };
  }
}