DOCSEARCHbyAlgolia
Submit Docs

Adobe CEP Getting Started Guides

repository·master·Indexed 20 days ago

https://github.com/adobe-cep/getting-started-guides

Guides for building Common Extensibility Platform (CEP) extensions for Adobe Creative Cloud applications including Photoshop, Illustrator, and InDesign. Covers enabling PlayerDebugMode, configuring .debug files for Chrome DevTools, using CSInterface.evalScript() to communicate with ExtendScript, making network requests via Fetch, and packaging extensions using ZXPSignCmd.

Tokens
12.5K
Snippets
29
Records
53
Agent score
70%

What's inside adobe-cep-getting-started-guides

  1. Alternative network request methods in CEP

    master

    While fetch() is the modern standard, CEP provides multiple ways to perform network requests due to its hybrid architecture:

    1. Chromium Embedded Framework (CEF): Since the UI is essentially a browser, you can use fetch(), XMLHttpRequest, or libraries like jQuery.
    2. Node.js: You can leverage Node.js capabilities within your extension to perform network requests using Node-specific modules.

  2. Understand the CEP extension architecture

    master

    A CEP (Common Extensibility Platform) extension consists of two main parts that communicate with each other:

    1. Client-side (Front-end): Built using standard web technologies (HTML, CSS, JavaScript). This part handles the User Interface (UI) and runs in a web browser environment. It uses the CSInterface.js library to communicate with the host application.
    2. Host-side (ExtendScript): Written in ExtendScript. This part has direct access to the host application's internal APIs (e.g., Photoshop, Illustrator) to perform tasks like opening documents, editing layers, or exporting files.

    Communication flows from the Client-side to the Host-side using the csInterface.evalScript() method.

  3. Handle license distribution for Marketplace plugins

    master

    If your plugin requires a license key for activation:

    1. Provide keys to reviewers: Share the license code in the "Notes to approver" section so the review team can activate the plugin during testing.
    2. Marketplace Integration: When users purchase your plugin via the Adobe Marketplace, the keys are managed via FastSpring. FastSpring will automatically distribute the license key to the end user.

  4. Understand CEP signature validation and certificate expiration

    master

    CEP extensions require a valid signature and certificate to run. The signature ensures the package hasn't been altered.

    Critical Note on Expiration: If a certificate expires and no valid timestamp was included during signing, the extension will fail to load. There is no user notification when this happens. To prevent service interruption, always include a timestamp when signing to extend the validity of the digital signature, and repackage your extension well before your certificate expires.

    Signature StatusCEP Result
    No signatureExtension does not run
    Signature invalidExtension does not run
    Certificate expired (no timestamp)Extension does not run
    Certificate expired (with valid timestamp)Extension runs normally
    Signature validExtension runs normally

  5. Create and configure a .debug file

    master

    To enable remote debugging, create a hidden file named .debug at the top level of your extension's folder. This file maps your Extension ID to specific host applications and debugging ports.

    Requirements:

    1. File Name: Must be exactly .debug (the leading dot makes it hidden).
    2. Extension ID: The Id attribute in the <Extension> tag must match the ID defined in your manifest.xml.
    3. Host Mapping: You must list the Host Name (e.g., PHXS for Photoshop) and assign a unique Port for debugging.

    Example .debug file content:

    <ExtensionList>
    <Extension Id="com.example.helloworld">
       <HostList>
           <Host Name="PHXS" Port="8088"/>
           <Host Name="PHSP" Port="8088"/>
        </HostList>
    </Extension>
</ExtensionList>
    <ExtensionList>
    <!-- 1 -->
    <Extension Id="com.example.helloworld">
       <HostList>

           <!-- 2 -->
           <Host Name="PHXS" Port="8088"/>
           <Host Name="PHSP" Port="8088"/>

        </HostList>
    </Extension>
</ExtensionList>

  6. Debug your extension in Chrome

    master

    Once the PlayerDebugMode is set and the .debug file is configured, you can use Chrome's DevTools to inspect your extension's JavaScript.

    1. Open Chrome.
    2. Navigate to http://localhost:<PORT>/ (replace <PORT> with the port you specified in your .debug file, e.g., http://localhost:8088/).
    3. You should see your extension's ID as a clickable link.
    4. Click the link to open the Chromium DevTools JavaScript Console. This is where you can view console.log() outputs and error messages from your extension's front-end code.

  7. Configure a complex package with an .mxi file

    master

    If your package includes files beyond the standard HTML extension (such as additional assets or installation instructions), you must provide a configuration .mxi file. This file specifies installation destinations, supported products, and file types. The .mxi file is used by the installer to manage the deployment of the extension and associated files.

    <?xml version="1.0" encoding="UTF-8"?>
<macromedia-extension
    id="id"
    icon="icon.png"
    name="Example Package"
    requires-restart="true"
    version="1.0.0">
    <author name="AUTHOR NAME"/>
    <description>
        <![CDATA[YOUR DESCRIPTION]]>
    </description>
    <ui-access>
        <![CDATA[YOUR INSTRUCTION]]>
    </ui-access>
    <license-agreement>
        <![CDATA[YOUR LICENSE AGREEMENT]]>
    </license-agreement>
    <products>
        <product familyname="Photoshop" version="13"/>
    </products>
    <files>
        <file source="Extension/html.zxp"
            destination=""
            file-type="CSXS"
            products="Photoshop,Photoshop32,Photoshop64"
            minVersion="14.0" />
        <file source="PSD/"
            destination="$Downloads"
            file-type="ordinary"
            products="Photoshop,Photoshop32,Photoshop64"
            minVersion="14.0" />
    </files>
</macromedia-extension>

  8. Request coupon codes for your plugin

    master

    You can request the Review Team to generate coupon codes for your customers. To do this, provide the following details to the Review Team:

    1. Extension name (or listing name).
    2. Coupon validity period (specific date range or perpetual).
    3. Percent off (the discount amount).
    4. Coupon code format:
      • Single coupon code: A unique string (e.g., MYCOUPON-FREE) stored on FastSpring.
      • Multiple Random Codes: Provide a five-character prefix; the Review Team will generate multiple random codes using that prefix.

  9. Submit a patch for a rejected submission

    master

    If your previous patch was rejected, follow these steps to resubmit:

    1. Go to the "Not Published" section in the Dashboard.
    2. Open the last rejected version.
    3. Click "Edit" and select the "Patch Details" tab.
    4. Replace the previously uploaded file with the corrected file. Note: The file type must match the original parent file type (e.g., if you originally uploaded a .zxp, you must upload a .zxp for the patch).

  10. Best practices for Adobe Exchange developers

    master

    Follow these best practices to improve plugin performance and user satisfaction:

    • Unified Developer ID: Use the same AdobeID for both UXP and CEP plugins to simplify tracking and management.
    • Regular Updates: Keep plugins compatible with the latest Adobe product versions to ensure a seamless user experience.
    • Test Credentials: Always share test credentials with the review team via the "Notes to Approver" section to expedite review.
    • License Management: If using FastSpring, share at least 100 license keys with the review team via the "Notes to Approver" section. Adobe will store these and distribute them to purchasers. If licenses run low, support@adobe.com will contact you.
    • User Support: Ensure users have a clear way to contact you to report problems and prevent poor reviews due to lack of communication.

  11. Prepare a plugin for Adobe Exchange review

    master

    To avoid rejection during the review process, ensure your plugin meets the following criteria:

    Functionality and Compatibility

    • Validate Features: Ensure all advertised features work as expected. The review team validates all functionality.
    • Handle Unsupported Actions: Do not fail silently. If a user attempts an unsupported function, display a dialog explaining that the action is not supported.
    • Match Compatibility Claims: The plugin must be compatible with all Adobe products, versions, and operating systems listed in your "Product Compatibility Information".

    Installation and Documentation

    • Detailed Instructions: Provide unique, descriptive installation instructions for every Adobe application supported. Specify the exact file paths and where users can find the plugin within the host application.
    • Clear Descriptions: Use the description field to explain features, functionality, and use cases. Including a video of the plugin in action is highly recommended.
    • Disclose Requirements: If your plugin requires a companion application or additional payments, this must be explicitly stated in the plugin description.

    Branding and Assets

    • Adhere to Branding Guidelines: Strictly follow the Adobe Branding Guidelines. Do not alter Adobe product icons. Use of Adobe assets without prior authorization will result in rejection.

  12. Set the Debug Mode to allow unsigned extensions

    master

    To prevent host applications (like Photoshop or InDesign) from blocking your extension with a "not properly signed" alert, you must enable PlayerDebugMode in the Adobe CSXS registry/preferences.

    Windows:

    1. Open regedit.
    2. Navigate to HKEY_CURRENT_USER/Software/Adobe/CSXS.8.
    3. Add a new entry named PlayerDebugMode of type string with the value 1.

    macOS: Run the following command in the Terminal:

    defaults write com.adobe.CSXS.8 PlayerDebugMode 1
    defaults write com.adobe.CSXS.8 PlayerDebugMode 1