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,
    };
  }
}

Authentication

onAuthenticationStatusQuery

Check the authentication status of the connector. If the connector has no valid authentication, it must respond with a url to let the user authenticate through the desired method.

onAuthenticationStatusQuery(request: ExternalSegmentAuthenticationStatusQueryRequest): promise<ExternalSegmentAuthenticationStatusQueryResponse>

Input parameters

request (ExternalSegmentAuthenticationStatusQueryRequest): Request sent at authentication checking.
Parameter
Type
Description

segment_id

string, optional

Optional identifier for the segment being queried

datamart_id

string

Identifier for the datamart associated with the authentication status query

plugin_version_id

string

Identifier for the version of the plugin being used

user_id

string

Unique identifier for the user making the authentication status query

properties

PluginProperty[], optional

Optional array of properties related to the plugin for additional context

Return

Resolves to an object containing the status of the authentication, and the login url if not authenticated.

Promise<ExternalSegmentAuthenticationStatusQueryResponse>

ExternalSegmentAuthenticationStatusQueryResponse object format:

Parameter
Type
Description

status

enum['authenticated' | 'not_authenticated' | 'error' | 'not_implemented']

Status of the authentication process indicating success or

message

string, optional

Message providing additional information about the authentication

data

object, optional

Optional object containing additional data related to the authentication status

data object format:

Parameter
Type
Description

login_url

string, optional

Optional URL for the login page if authentication is

any key

string, optional

Additional properties can be included in this object as needed

Code

Code example
protected async onAuthenticationStatusQuery(
  request: ExternalSegmentAuthenticationStatusQueryRequest,
): Promise<ExternalSegmentAuthenticationStatusQueryResponse> {
  this.logger.info(`onAuthenticationStatusQuery - Checking for User: ${request.user_id}.`);

  try {
    const usersCredentials = await this.retrieveUsersCrendentials();
    const userCredential = usersCredentials[request.user_id];

    if (!userCredential) {
      this.logger.info(
        `onAuthenticationStatusQuery - No credentials found for user: ${request.user_id}. Starting authentication flow.`,
      );

      const encryption_key = await this.retrieveEncryptionKey()
      const client_id = await this.retrieveMicsClientId()

      const state = `datamart_id:${request.datamart_id}&user_id:${request.user_id}`;
      const encryptedState = this.encryptString(state, encryption_key);
      const encodedState = encodeURIComponent(encryptedState);

      const micsRedirectUri = `https://navigator.mediarithmics.com/v2/plugin_versions/${request.plugin_version_id}/auth_callback`;
      const loginUrl = `https://www.partner.com/oauth/authorization?response_type=code&client_id=${client_id}&redirect_uri=${micsRedirectUri}&state=${encodedState}`;

      return {
        status: 'not_authenticated',
        message: `No credentials found in the users credentials file for user: ${request.user_id}.`,
        data: {
          login_url: loginUrl,
        },
      };
    }

    const isRefreshTokenValid = await this.checkRefreshTokenValidity(request.user_id);

    if (!isRefreshTokenValid) {
      return {
        status: 'not_authenticated',
        message: `User ${request.user_id} was logged out due to invalid refresh token.`,
      };
    }

    return {
      status: 'authenticated',
      message: `User ${request.user_id} is authenticated.`,
    };
  } catch (err) {
    this.logger.error(`onAuthenticationStatusQuery - something went wrong:`, err);
    return {
      status: 'error',
      message: (err as Error).message,
    };
  }
}

onAuthentication

Handle the redirection from the partner authentication flow and authenticate the connection within mediarithmics.

onAuthentication(request: Request): promise<Response>

Input parameters

request (ExternalSegmentAuthenticationRequest): Request forwarded from the partner response after authentication on their
Parameter
Type
Description

user_id

string

unique identifier for the user making the authentication request

plugin_version_id

string

identifier for the version of the plugin being used for authentication

params

object, optional [key: string]

Optional object containing additional parameters received in the redirection from the partner authentication. Concerning the Oauth2.0 protocol, the code is present within this array

Return

Resolves to an object containing the response status along the optional message.

Promise<ExternalSegmentAuthenticationResponse>
Parameter
Type
Description

status

enum['ok' | 'error' | 'not_implemented']

Status of the authentication process indicating success or failure

message

string, optional

optional message providing additional information about the authentication status

Code

Code example
protected async onAuthentication(
  request: ExternalSegmentAuthenticationRequest,
): Promise<ExternalSegmentAuthenticationResponse> {
  this.logger.info(
    `onAuthentication - Response received from partner. Converting User ${request.user_id}'s code into a refresh token and storing it.`,
  );

  try {
    if (!request.params || !Object.keys(request.params).length) {
      throw new Error('No params found in request.');
    }

    const encryption_key = await this.retrieveEncryptionKey()
    const expectedKeys = ['code', 'state'];
    const missingKeys = expectedKeys.filter((key) => !request.params?.[key]);

    if (missingKeys.length) {
      throw new Error(`Missing keys in request.params: ${missingKeys.join(', ')}`);
    }

    const encryptedState = request.params['state'];
    const decryptedState = this.decryptString(encryptedState, encryption_key);

    const state = this.parseAndValidateState(decryptedState);

    this.logger.info(`onAuthentication - state decrypted and parsed:`, state);

    const code = request.params['code'];
      
    const refresh_token = await retrieveRefresehToken(code);
    await storeRefreshToken(refresh_token);

    this.logger.info(
      `onAuthentication - Refresh token received and stored for user ${request.user_id}.`,
    );

    return {
      status: 'ok',
    };
  } catch (err) {
    const requestError = (err as RequestError).response?.body || 'Unknown error';
    this.logger.error(`onAuthentication - something went wrong:`, {
      error: requestError
        ? typeof requestError === 'string'
          ? requestError
          : JSON.stringify(requestError)
        : JSON.stringify(err as Error),
    });
    return {
      status: 'error',
      message: (err as Error).message,
    };
  }
}

onLogout

Handle the connector logout for either a user, or a datamart.

onLogout(request: ExternalSegmentLogoutRequest): Promise<ExternalSegmentLogoutResponse>

Input parameters

request (ExternalSegmentLogoutRequest): Request sent when logging out
Variable
Type
Description

user_id

string

Unique identifier for the user making the logout request

plugin_version_id

string

Identifier for the plugin version being used for the logout

datamart_id

string

Identifier for the datamart associated with the logout request

Return

Resolves to an object containing the response status along the optional message.

Promise<ExternalSegmentLogoutResponse>

Parameter
Type
Description

status

enum['ok' | 'error' | 'not_implemented']

Status of the authentication process indicating success or failure

message

string, optional

Optional message providing additional information about the authentication status

Code

Code example
protected async onLogout(request: ExternalSegmentLogoutRequest): Promise<ExternalSegmentLogoutResponse> {
  this.logger.info(`onLogout - Loging out User: ${request.user_id}.`);

  try {
    const userLoggedOut = await this.logoutUser(request.user_id);
    return {
      status: 'ok',
      message: `Successfully logged out user ${request.user_id}.`,
    };
  } catch (err) {
    this.logger.error(`onLogout - something went wrong:`, err);
    return {
      status: 'error',
      message: (err as Error).message,
    };
  }
}

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,
    };
  }
}

Last updated

Was this helpful?