Integrations

Blue Blocker exposes an API to allow other extensions to interact with it. Extensions can provide additional checks for Twitter users (eg. Soupcan's check for transphobes), use Blue Blocker's blocking logic without implementing block logic internally (eg. an extension that blurs tweets can optionally also block the author), or both.

Usage

Users can enable integrations with other extensions by navigating to the integrations page (found in the advanced tab of Blue Blocker's popup), and entering the extension ID(s) and name(s) for the integrations they want to activate.

Registration

In addition to the manual process described above, your extension can initiate the integration registration process programmatically. To do so send a message that conforms to the following interface to Blue Blocker:

interface RegistrationRequest {
  action: "register",
  name: string
}

If your extension registers using this method the integration will initially be set to disabled, until the user activates it. Further registration messages from your extension will be ignored if it has already been registered previously.

API

States

Blue Blocker lets users decide what level of integration they want Blue Blocker and an external extension to have. The four states are:

• Disabled - The integration is off
• Receive only - Blue Blocker will accept input from the external extension but will not send data to it
• Send only - Blue Blocker will send data to the external extension but will not accept input from it
• Send and receive - Blue Blocker will send data to the external extension and accept data from it

Sending

If an integration has a state that allows sending, BlueBlocker will send all users it finds to the external extension. The message sent will have the following interface:

interface BlueBlockerMessage {
  action: 'check_twitter_user',
  data: BlueBlockerUser,
  refid: number
}

For details on the BlueBlockerUser interface, see src/global.d.ts. After receiving the message the external extension is expected to send back a message with the following interface:

interface ExternalResponse {
  status: "SUCCESS" | "ERROR",
  message?: any, // only include if status is "ERROR"
  result?: {
    block: boolean, // whether BlueBlocker should block the user
    reason?: string // BlueBlocker will use this string to tag the block internally
  }
}

Receiving

If an integration has a state that allows receiving, Blue Blocker will listen for messages. All messages must be objects and have the following interface:

interface ExternalMessage {
  action: "BLOCK" | "block_user",
  name?: string, // only used if action == "BLOCK"
  screen_name?: string, // only used if action == "BLOCK"
  reason?: string, // only used if action == "BLOCK"
  data?: BlockUser // only used if action == "block_user"
}

For details on the BlockUser interface see src/global.d.ts. After handling the message, Blue Blocker will respond with an object with the following interface:

interface ResponseToExternal {
  status: "ERROR" | "SUCCESS",
  message?: string, // error message
  result?: string // success message
}

Example extension

An example extension is available as a reference.

Issues and suggestions

For extension developers

If you find any errors in how Blue Blocker integrates with your extension, please create an issue in this repo. If possible please include any relevant logs (from both extensions please), and browser/platform information (e.g. Chrome 110 on Windows 11). See How To Make An Issue. Also feel free to use issues to suggest changes and/or enhancements to the integration API.

For users

Feel free to create an issue (in this repo) if you find errors. If possible please include any relevant logs (from both extensions please), and browser/platform information (e.g. Chrome 110 on Windows 11). See How To Make An Issue. If the other extension is open source, please include a link to that repo and tag the author in your issue. If you create an issue on the other extension's repo, please tag a Blue Blocker maintainer (preferably @rougetimelord or @cooljeanius).