@excojs/placement-sdk

EXCO Placement SDK

This package allows you to manage placements from app.ex.co in programmatic way.

Installation

To install it by npm just use

npm install @excojs/placement-sdk

How to use

To make it works firstly you need to load SDK by a method

/**
 * Loads EXCO SDK by tagId
 * @param tagId - tag id from your app.ex.co account
 * @param target - DOM element OR Promise with DOM element to append script
 * @returns - Promise that will be resolved after script append.
 */
function loadSDK(
  tagId: string,
  target: HTMLElement | Promise<HTMLElement> = document?.body
): Promise<void>;

After that, you can create an instance of

class EXCO_PlacementClient implements IPlacementClient {
  constructor(placementId: string) {}
}

that allows you to manipulate placements by placement ID.

Interface

Here is an interface for EXCO_PlacementClient class

interface IPlacementClient {
  /**
   * Allows to mount placement on page for specific DOM element or to document.body by defalut
   * @param target DOM element for mounting placement
   */
  mount(target: HTMLElement): Promise<this>;
  /**
   * Unmounts placement
   */
  unmount(): void;
  /**
   * Publish action in pubSub of placement.
   * @param target Parent elemnt for sdk script tag
   */
  publish(action: ExcoActions, data: any): void;
  /**
   * Subscribes on actions from placement by action name
   * @param action - action name
   * @param callback - callback that will be called on action
   */
  subscribe(action: ExcoActions, callback: Function): SubscriptionKey;
  /**
   * Unsubscribes from action
   * @param key - it can be subscription key that returns after subscribe or action name
   */
  unsubscribe(key: SubscriptionKey | ExcoActions): void;
}

Example

async function example(tagId, placementId, target) {
  // load sdk is required
  await loadSDK(tagId);
  
  // client creation
  const placement = new EXCO_PlacementClient(placementId);

  // mount placement to target DOM element
  await placement.mount(target);

  // subscribe on Call To Action button click
  await placement.subscribe('pb.cta.clicked', async (actionName) => {
    // do some action on user 'call to action' click and unsubscribe
    placement.unsubscribe(actionName);
  });
}

Possible actions (events) to subscribe and/or publish

{
    SDK: {
        RENDER: 'sdk_render',
    },
    EXPERIENCE: {
        LOAD: 'experience_load',
        HIDE: 'experience_hide',
    },
    PLACEMENT: {
        LOAD: 'placement_load',
        TRIGGER: 'trigger_action',
        TRIGGER_OPEN: 'trigger_open',
        TRIGGER_CLOSE: 'trigger_close',
        TRIGGER_HIDE: 'trigger_hide',
    },
    ITEM: {
        LOAD: 'pb.item.load',
        IDLE: 'pb.item.idle',
        RENDER: 'pb.item.render',
        PROGRESS: 'pb.item.progress',
        SHARE: 'pb.item.share',
        CHANGE: 'pb.item.change',
        SCROLL_TOP_INTO_VIEW: 'pb.item.scroll-top-into-view',
        SCROLL_TOP_OUT_OF_VIEW: 'pb.item.scroll-top-out-of-view',
        SCROLL_BOTTOM_INTO_VIEW: 'pb.item.scroll-bottom-into-view',
        SCROLL_BOTTOM_OUT_OF_VIEW: 'pb.item.scroll-bottom-out-of-view',
        POWERED_BY_LINK: 'pb.item.powered-by-link',
        PLACEMENT_COMPLETED: 'pb.placement-unit.completed',
        PLACEMENT_HEIGHT: 'pb.placement-unit.height'
    },
    SECTION: {
        VIEW: 'pb.section.view',
        SHARE: 'pb.section.share',
        RANK: 'pb.section.rank',
        FLIP: 'pb.section.flip',
        POLL_VOTE: 'pb.section.poll-vote',
        POLL_BEFORE_VOTE: 'pb.section.poll-before-vote',
        POLL_COMPLETION: 'pb.section.poll-completion',
        POLL_RESULT: 'pb.section.poll-result',
        POLL_END_CARD: 'pb.section.poll-end-card',
        POLL_END_EMPTY: 'pb.section.poll-end-empty',
        IMAGE_UNBLUR: 'pb.section.image-unblur',
        IMAGE_COMPLETION: 'pb.section.image-completion',
        IMAGE_LOADED: 'pb.section.image-loaded',
        CALL_TO_ACTION_CLICK: 'pb.section.call-to-action-click',
        PARAGRAPH_HYPERLINK_CLICK: 'pb.section.paragraph-hyperlink-click',
        IFRAME_EVENT_FIRE: 'pb.section.iframe-event-fire',
        SCROLL_INTO_VIEW: 'pb.section.scroll-into-view',
        SCROLL_OUT_OF_VIEW: 'pb.section.scroll-out-of-view',
        VIDEO_PLAYER_PLAY: 'pb.section.video-player-play',
        VIDEO_PLAYER_START: 'pb.section.video-player-start',
        VIDEO_PLAYER_PAUSE: 'pb.section.video-player-pause',
        VIDEO_PLAYER_3_SEC_PLAY: 'pb.section.video-player-3-sec-play',
        VIDEO_PLAYER_FINISH: 'pb.section.video-player-finish',
        VIDEO_PLAYER_READY: 'pb.section.video-player-ready',
        QUIZ_START: 'pb.section.quiz-start',
        QUIZ_QUESTION_ANSWERED: 'pb.section.quiz-question-answered',
        QUIZ_QUESTION_BEFORE_ANSWERED: 'pb.section.quiz-question-before-answered',
        QUIZ_COMPLETION: 'pb.section.quiz-completion',
        QUIZ_RESULT: 'pb.section.quiz-result',
        QUIZ_CONTINUE_BTN_CLICKED: 'pb.section.quiz-continue-btn.clicked',
        TRIVIA_CONTINUE_BTN_CLICKED: 'pb.section.trivia-continue-btn.clicked',
        TRIVIA_QUESTION_ANSWERED: 'pb.section.trivia-question-answered',
        TRIVIA_QUESTION_BEFORE_ANSWERED: 'pb.section.trivia-question-before-answered',
        TRIVIA_GO_BACK_CLICK: 'pb.section.trivia-go-back-click',
        TRIVIA_COMPLETION: 'pb.section.trivia-completion',
        TRIVIA_RESULT: 'pb.section.trivia-result',
        JOURNEY_START: 'pb.section.journey-start',
        JOURNEY_QUESTION_LOADED: 'pb.section.journey-question-loaded',
        JOURNEY_QUESTION_ANSWERED: 'pb.section.journey-question-answered',
        JOURNEY_QUESTION_BEFORE_ANSWERED: 'pb.section.journey-question-before-answered',
        JOURNEY_COMPLETION: 'pb.section.journey-completion',
        JOURNEY_RESULT: 'pb.section.journey-result',
        JOURNEY_CONTINUE_BTN_CLICKED: 'pb.section.journey-continue-btn.clicked',
        CHECKLIST_RESULT: 'pb.section.checklist-result',
        CHECKLIST_ANSWER: 'pb.section.checklist-answer',
        LEAD_FORM_COMPLETION: 'pb.section.lead-form-completion',
        LEAD_FORM_SUBMIT: 'pb.section.lead-form-submit',
        LEAD_FORM_FOCUS: 'pb.section.lead-form-focus',
        LEAD_FORM_NEXT: 'pb.section.lead-form-next',
        LEAD_FORM_PREVIOUS: 'pb.section.lead-form-previous',
        LEAD_FORM_IMPRESSION: 'pb.section.lead-form-impression',
        LEAD_FORM_INPUT_FOCUS: 'pb.section.lead-form-input-focus',
        PRODUCT_CLICKED: 'pb.section.products-gallery.clicked',
    },
    MEDIA: {
        FLIP_CARD: {
            CLICK: 'pb.media.flip-card.click'
        },
        IMAGE: {
            UNBLUR: 'pb.media.image.unblur'
        }
    },
    VIDEO_SNAPS: {
        PLAY: 'pb.video-snaps.play',
        PAUSE: 'pb.video-snaps.pause',
        MUTE: 'pb.video-snaps-mute',
        SNAP_CHANGE: 'pb.video-snaps.snap.change',
        SNAP_PROGRESS: 'pb.video-snaps.snap.progress',
        READY: 'pb.video-snaps.ready'
    },
    VIDEO_CREATOR: {
        HEART_BEAT: 'pb.video-creator.heart-beat',
        MILESTONE: 'pb.video-creator.milestone',
        USER_CLICKED_PLAY: 'pb.video-creator.user-clicked-play',
        USER_CLICKED_MUTE: 'pb.video-creator.user-clicked-mute',
        USER_CLICKED_FULL_SCREEN: 'pb.video-creator.user-clicked-full-screen',
        USER_CLICKED_PROGRESS_BAR: 'pb.video-creator.user-clicked-progress-bar',
        USER_CLICKED_REPLAY: 'pb.video-creator.user-clicked-replay',
        VIDEO_READY: 'pb.video-creator.video-ready',
        VIDEO_PLAYER_LOADED: 'pb.video-creator.video-player-loaded',
        VIDEO_STARTS_PLAYING: 'pb.video-creator.video-starts-playing',
        USER_CLICKED_PAUSE: 'pb.video-creator.user-clicked-pause',
        VIDEO_COMPLETE: 'pb.video-creator.video-complete',
        FB_CROSSPOST_CLICK: 'pb.video-creator.fb-crosspost-click',
        FB_CROSSPOST_SUCCESS: 'pb.video-creator.fb-crosspost-success',
        VIDEO_ERROR: 'pb.video-creator.video-error',
        VIDEO_IN: 'pb.video-creator.video-in'
    },
    SHARE_BAR: {
        IMPRESSION: 'pb.share-bar.impression',
        BUTTON_CLICK: 'pb.share-bar.button-click'
    },
    ADS: {
        PLACEMENTS_READY: 'ads.placements-ready'
    },
    CTA: {
        LOADED: 'pb.cta.loaded',
        CLICKED: 'pb.cta.clicked'
    },
    BINGE: {
        COMPLETED: 'pb.binge.completed'
    },
    SAAS: {
        JOIN_TRIAL: 'pb.saas.join-trial'
    },
    TRIAL_TOOLTIP: {
        OPEN: 'pb.trial-tooltip.open',
        LINK_CLICK: 'pb.trial-tooltip.link-click'
    },
    INVITE_USERS: {
        OPEN_MODAL: 'pb.invite-users.open-modal',
    },
    NAVBAR_MODALS: {
        OPEN: 'open',
        CLOSE: 'close',
        LOCKED_FEATURE_CLICKED: 'lockedFeatureClicked',
        LOCKED_FEATURE_UNCLOSEABLE: 'lockedFeatureUncloseable'
    },
    TEXT_EDITOR: {
        ILLEGAL_TEXT: 'illegalText'
    },
    VIDEO_CONSOLE: {
        YOUTUBE_IMPORT_AUTH_MODAL_OPEN: 'youtube-import-auth-modal-open',
        YOUTUBE_IMPORT_VIDEO_LIST_FOR_IMPORT: 'youtube-import-video-list-for-import'
    }
};