Dev Guide
Dev GuideUser GuideGitHubNuGetDevCommunityDoc feedbackLog In
GitHubNuGetDevCommunityDoc feedback

OCP App SDK / Channel

Channel

Defines the interface of a channel. The typical channel flow in a campaign run is as follows:

  1. Check if the channel is ready to use
  2. Dynamically determine the target (may be provided statically in app.yml instead)
  3. publish the content template (in the future, this will instead happen when the campaign is modified)
  4. prepare for the run (if the method is implemented)
  5. deliver the content to batches of recipients with substitutions

Outside of the campaign run flow, a channel must also be able to preview a given piece of content for a batch
of recipients.

Index

Constructors

Methods

Constructors

constructor()

Signature

new Channel(): Channel;

Returns

Channel

Methods

deliver()

Delivers a batch of messages. This method may be called many times for the same content key, tracking parameters,
and options, each with a unique batch of recipients and substitutions. It is assumed that a batch either succeeds
or fails as a whole. There is no partial delivery handling.

If a batch fails, it may be retried (as controlled by the return value). When that happens, the subsequent call(s) for that batch will be given the previous result for reference to enable proper recovery logic.

Once a batch succeeds, it will never be given again.

Async

Signature

Abstract deliver(
  contentKey: string,
  tracking: CampaignTracking,
  options: ChannelDeliverOptions,
  batch: CampaignDelivery[],
  previousResult?: ChannelDeliverResult): Promise<ChannelDeliverResult>;

Parameters

NameTypeDescription
contentKeystringunique key of the content
trackingCampaignTrackingcampaign tracking parameters
optionsChannelDeliverOptionsadditional options
batchCampaignDelivery[]of recipients and substitutions
previousResult?ChannelDeliverResultprevious result of the operation, if this is a retry

Returns

Promise<ChannelDeliverResult>

result of the operation

Defined in: src/app/Channel.ts:107

prepare()?

Prepares for a campaign run. This can be used to set up an external entity for use in deliver (or perform any
other processing that should only be performed once per run). If this step is unnecessary, simply do not implement
the method.

If implemented, this method will be called exactly once per content key involved in a campaign run. If any one of these fails, the campaign run will fail.

Async

Signature

Optional prepare(contentKey: string, tracking: CampaignTracking, options: ChannelPrepareOptions): Promise<ChannelPrepareResult>;

Parameters

NameTypeDescription
contentKeystringunique key of the content
trackingCampaignTrackingcampaign tracking parameters
optionsChannelPrepareOptionsadditional options

Returns

Promise<ChannelPrepareResult>

result of the operation

Defined in: src/app/Channel.ts:86

preview()

Renders a batch of messages into HTML previews. Each preview must be a full HTML page containing a user-friendly
representation of the message as it would be delivered.

Async

Signature

Abstract preview(content: CampaignContent, batch: CampaignDelivery[]): Promise<ChannelPreviewResult>;

Parameters

NameTypeDescription
contentCampaignContentthe content with translated templates
batchCampaignDelivery[]of recipients and substitutions

Returns

Promise<ChannelPreviewResult>

result of the operation

Defined in: src/app/Channel.ts:123

publish()

Publishes the given content. This is the place to perform any necessary transformations between the given template
format and the external system's format. It can be assumed that validate has already been called,
but additional errors may still be detected in this phase and returned in the same way as during validation.

If the content must be stored in an external system, this is also the time to do that. If the content must instead be known in `prepare` or `deliver`, it should be placed in the document store for future use.

This method may be called multiple times with the same content key. But for a given content key, it will always be called with the same content and options. As such, once successful, it should be treated as an idempotent operation at the content key level. So if the given key has already been processed and successfully stored, there is no need to process and store it again.

Async

Signature

Abstract publish(contentKey: string, content: CampaignContent, options: ChannelPublishOptions): Promise<ChannelContentResult>;

Parameters

NameTypeDescription
contentKeystringunique key for the content
contentCampaignContentthe content with translated templates
optionsChannelPublishOptionsadditional options

Returns

Promise<ChannelContentResult>

result of the operation

Defined in: src/app/Channel.ts:69

ready()

Checks if the channel is ready to use. This should ensure that any required credentials and/or other configuration
exist and are valid. Reasonable caching should be utilized to prevent excessive requests to external resources.

Async

Signature

Abstract ready(): Promise<boolean>;

Returns

Promise<boolean>

true if the channel is ready to use

Defined in: src/app/Channel.ts:23

target()?

Dynamically determines campaign targeting requirements. It should also perform any necessary validations on the
input data. If targeting is always known ahead of time, this should be specified statically via channel.targeting
in app.yml. If targeting is based on selections made in the content settings form, this method must be
implemented and the value in app.yml must be set to dynamic.

Async

Signature

Optional target(contentSettings: FormData): Promise<ChannelTargetResult>;

Parameters

NameTypeDescription
contentSettingsFormDatadata from the content settings form

Returns

Promise<ChannelTargetResult>

result of the operation

Defined in: src/app/Channel.ts:34

templatePreview()

Renders an untranslated template (containing Liquid code rather than substitution identifiers) to HTML to be
used for thumbnail creation for users to browse templates for this channel. Thumbnails will be generated at
resolution of 600px by 600px with a 50% scale factor (actual size 300px by 300px).

Async

Signature

templatePreview(template: FormData): Promise<ChannelTemplatePreviewResult>;

Parameters

NameTypeDescription
templateFormDatathe untranslated template

Returns

Promise<ChannelTemplatePreviewResult>

result of the operation

Defined in: src/app/Channel.ts:136

validate()

Validates the given content. This should ensure that the content is suitable for use in the current mode, as
specified in the options (see mode). If specific fields are missing or invalid,
appropriate error messages should be provided using addError. Any errors that are
not linked to a specific field should be provided using addToast. If no errors of
either type are returned, the validation is considered successful, and the operation will be allowed to proceed.

Async

Signature

Abstract validate(content: CampaignContent, options: ChannelValidateOptions): Promise<ChannelContentResult>;

Parameters

NameTypeDescription
contentCampaignContentthe content with translated tempaltes
optionsChannelValidateOptionsadditional options

Returns

Promise<ChannelContentResult>

result of the operation

Defined in: src/app/Channel.ts:47