Guide 1.18: Developer Integration, Extensibility and Customisation
1. Introduction
SmartDescribe Pro helps WooCommerce store owners improve product image alt text using AI. Developers may want to customise the surrounding workflow, integrate optimisation into existing store-management processes, or investigate how the plugin interacts with WordPress and WooCommerce.
This guide explains the main integration considerations, how to plan customisations safely, and how to assess whether a requested extension is supported by the installed plugin.
It is intended for:
- WordPress developers.
- WooCommerce developers.
- Website maintenance providers.
- Agencies maintaining client stores.
- Advanced store administrators planning custom workflows.
Important: This guide describes general WordPress and WooCommerce development practices. It does not claim that SmartDescribe Pro exposes a particular hook, filter, API endpoint, class, function, command, or database structure unless that feature is explicitly documented for the installed version. Always inspect the actual plugin release before implementing an integration.
2. Understanding the Integration Environment
SmartDescribe Pro operates within a WordPress environment that may also include WooCommerce, a theme, SEO plugins, image optimisation tools, caching systems, and other extensions.
A typical workflow involves several components:
- WooCommerce provides product records.
- WordPress manages media attachments and image metadata.
- SmartDescribe Pro identifies eligible images and processes optimisation requests.
- The configured AI provider generates text.
- WordPress stores the resulting alt text.
- WooCommerce and the active theme display product images on the public website.
- Other plugins may use or modify product and image information.
The exact implementation depends on the installed version.
When planning an integration, identify which component is responsible for the operation you want to change.
For example:
- Changing how generated text is displayed may involve the theme or image-rendering process.
- Changing which products are eligible may involve product selection and plugin workflow logic.
- Changing stored alt text involves WordPress attachment metadata.
- Changing the AI provider involves the plugin’s provider integration and configuration.
Understanding these boundaries reduces the risk of modifying the wrong component.
3. What Can Be Customised?
The available customisation options depend on the features exposed by SmartDescribe Pro and the requirements of the website.
Potential areas for customisation include:
- Product selection workflows.
- Category-based content requirements.
- Internal review and approval procedures.
- Reporting and quality-control processes.
- Developer diagnostics.
- Connections with existing store-management systems.
- Custom administrative workflows.
- Integration with other tools that consume WordPress image metadata.
Before planning a custom feature, establish whether the installed version already supports it through its settings or documented interface.
If the feature is not available, determine whether it can be implemented safely through a documented extension point or whether it would require a change to the plugin itself.
Do not assume that a setting available in another version, edition, or plugin is also present in the installed release.
4. Should You Use a Plugin Setting, Hook, or Custom Code?
When extending SmartDescribe Pro, use the least invasive method that meets the requirement.
Option 1: Existing plugin settings
Use the built-in settings when they already provide the required behaviour.
Advantages include:
- Lower maintenance overhead.
- Reduced risk of conflicts.
- Easier administration.
- Better compatibility with future plugin updates.
Option 2: Documented extension points
If SmartDescribe Pro documents hooks, filters, APIs, or other extension points for your installed version, these may allow custom behaviour without editing the plugin’s core files.
Before using an extension point, confirm:
- Its name and purpose.
- The arguments it receives.
- Whether it runs before or after the relevant operation.
- What value it expects a callback to return.
- Whether its behaviour is covered by the plugin’s compatibility commitments.
Option 3: A separate custom plugin
When custom behaviour is required and no suitable built-in setting or documented extension point exists, a separate site-specific plugin may be appropriate.
A separate plugin can keep custom logic distinct from the distributed SmartDescribe Pro files.
However, it should only call documented or verified interfaces. Creating a separate plugin does not make undocumented dependencies safe.
Option 4: Modifying SmartDescribe Pro directly
Direct source-code modifications should generally be a last resort.
They can be overwritten by updates, introduce new errors, and make future support more difficult.
If a direct modification is unavoidable, document it, test it on staging, and establish a maintenance plan.
5. Working With WooCommerce Product Data
WooCommerce products contain information that may help determine which products should be included in a custom workflow.
Examples include:
- Product name.
- Product description.
- Short description.
- Product category.
- Product type.
- Product status.
- Featured image.
- Product gallery images.
Not every field is necessarily used by SmartDescribe Pro during optimisation. The available product-selection criteria depend on the installed version.
Recommended development approach
- Identify the business requirement.
- Determine which product fields are needed.
- Confirm how the installed plugin identifies eligible products.
- Check whether the required selection feature already exists.
- If custom code is necessary, use WooCommerce and WordPress APIs where appropriate.
- Test with different product types and incomplete product records.
Do not assume every product has a featured image or that every image attached to a product is eligible for optimisation.
Also consider variable products, draft products, private products, and products that share the same image attachment.
A robust integration should handle missing data without producing fatal errors.
6. Working With WordPress Image Attachments
WordPress generally stores uploaded images as media attachments. These attachments have their own identifiers and metadata.
A WooCommerce product can reference an attachment as its featured image and may also reference additional images in its gallery.
This distinction is important because the product ID and image attachment ID are not necessarily the same.
General WordPress alt text storage
WordPress commonly stores an attachment’s alternative text in the _wp_attachment_image_alt metadata field.
Developers investigating a custom integration should establish:
- Which attachment is being processed.
- Whether the attachment exists.
- Whether the image is used by multiple products.
- Whether the existing alt text should be preserved.
- Whether the intended update should affect one image or several.
- Whether another component modifies the value.
Use WordPress-supported APIs to retrieve or update attachment metadata rather than issuing direct database updates without a clear reason.
Shared image considerations
If the same image is used on multiple products, changing the attachment’s alt text may affect how the image is described in several locations.
Before implementing automatic changes, decide whether shared images should use a single consistent description or require a different description in a particular context.
Do not assume that one attachment can have different saved alt text values for every product that uses it. The rendered alternative text may depend on the context and implementation.
7. Integrating With SEO Plugins
WooCommerce stores may use SEO plugins to manage page titles, meta descriptions, structured data, and other search-related information.
Image alt text is a separate concern from page-level SEO metadata.
A custom integration should identify the precise data that needs to be exchanged.
For example:
- A product’s SEO title is not the same as its image alt text.
- A product’s meta description is not a replacement for an image description.
- Structured data does not automatically correct an unsuitable alt attribute.
- Changing image metadata does not necessarily change the page’s title or meta description.
If your installation uses Yoast SEO, Rank Math, or another SEO plugin, verify which component controls the relevant output before implementing custom code.
Do not write to another plugin’s internal metadata fields unless its documentation confirms that the fields are appropriate for the intended purpose.
8. Integrating With External AI Providers
SmartDescribe Pro uses its configured AI provider to generate image alt text.
When planning a custom AI integration, consider the following questions:
- Does the installed SmartDescribe Pro version already support the required provider?
- Is the required model supported by the plugin?
- Does the provider accept the input format used by the integration?
- What are the provider’s authentication requirements?
- What limits apply to requests, image inputs, and generated output?
- How are errors reported?
- How are credentials stored and protected?
If the installed version already supports the required provider and model, use its existing configuration wherever possible.
Avoid building a second, independent AI request system without a clear need. Duplicated integrations can create inconsistent settings, additional API costs, and separate error-handling requirements.
Provider-specific considerations
Different providers may use different:
- API endpoints.
- Authentication methods.
- Model identifiers.
- Request formats.
- Response formats.
- Usage limits.
- Error codes.
A custom integration should follow the selected provider’s current documentation rather than assuming that all providers work identically.
Never place private API keys in front-end JavaScript or expose them in publicly accessible source code.
9. Building Custom Review and Approval Workflows
Some stores may want AI-generated alt text to be reviewed before it is used publicly.
A custom workflow might involve:
- Selecting eligible products.
- Generating proposed alt text.
- Reviewing the proposed descriptions.
- Approving or editing the text.
- Saving the approved result.
- Recording the review status.
Before building such a workflow, establish whether the installed version already provides a suitable review mechanism.
If custom development is required, consider:
- Which user roles can review or approve text.
- Whether generated text should replace existing alt text automatically.
- How rejected suggestions are handled.
- How approval status is recorded.
- How changes are audited.
- How the workflow behaves when multiple users edit the same product.
- Whether the process supports individual and bulk operations.
Avoid implementing approval states by repurposing unrelated WordPress metadata fields without a clear design.
A separate, documented data model may be more appropriate when the workflow needs to track proposed text, approved text, reviewers, and timestamps independently.
10. Reporting and Quality-Control Integrations
A store may want to report on image descriptions across its product catalogue.
Potential reporting objectives include:
- Finding images with missing alt text.
- Identifying products with incomplete image information.
- Reviewing descriptions that exceed a preferred length.
- Checking for repeated or generic descriptions.
- Identifying products awaiting human review.
- Measuring how much of a catalogue has been reviewed.
These are possible custom reporting objectives, not a claim that every report is built into SmartDescribe Pro.
Recommended approach
- Define the report’s purpose.
- Identify the WordPress records and metadata needed.
- Establish how image attachments map to products.
- Define what counts as missing or incomplete alt text.
- Decide whether shared images should be counted once or once per product.
- Test the report against a small, manually checked sample.
- Document any limitations.
A report should distinguish between an image with no alt text and an image that intentionally uses an empty alt attribute because it is decorative.
Do not treat every empty alt attribute as an error without considering the image’s purpose and context.
11. Security Requirements for Custom Integrations
Custom code that interacts with WordPress, WooCommerce, or AI providers must be designed with security in mind.
Permissions
Administrative actions should require suitable capability checks.
Do not assume that hiding an interface button prevents an unauthorised request.
Request verification
For applicable administrative actions, use appropriate request verification and nonce checks. A nonce is not a replacement for permission checks.
Input validation and sanitisation
Validate incoming values against the expected data type and range. Sanitise input appropriately before processing or storing it.
Output escaping
Escape values according to the context in which they are displayed, such as HTML attributes, HTML content, or JavaScript.
API credentials
- Keep API keys server-side.
- Do not expose credentials in front-end code.
- Avoid writing complete keys to logs.
- Restrict access to settings and diagnostic output.
- Rotate keys that may have been exposed.
External requests
Use appropriate WordPress HTTP APIs and handle failures safely. Do not assume that every external response is valid or successful.
These are general WordPress development principles. They should not be interpreted as a statement that a particular SmartDescribe Pro release implements a specific security control without verification.
12. Performance and Scalability
Custom integrations can affect website performance, especially when processing large catalogues.
Potential risks include:
- Processing too many products in one request.
- Repeatedly requesting the same information.
- Making unnecessary AI calls.
- Exceeding provider quotas.
- Running long operations during normal administration.
- Consuming excessive memory.
- Generating duplicate scheduled tasks.
Recommended practices
- Test with a small product selection.
- Avoid unnecessary repeated API requests.
- Use appropriate query limits and pagination.
- Consider background processing for long-running operations where suitable.
- Record meaningful errors without generating excessive logs.
- Monitor API usage and costs.
- Test performance on a staging site with a representative catalogue.
Do not assume that SmartDescribe Pro uses a particular background-processing library or queue mechanism. Confirm the installed implementation before attempting to integrate with it.
13. Compatibility and Maintenance
Custom integrations must be maintained as WordPress, WooCommerce, SmartDescribe Pro, and external AI providers evolve.
Before updating any component:
- Review the relevant release notes.
- Identify any documented changes to APIs or extension points.
- Back up the website.
- Test the update on staging.
- Test individual optimisation.
- Test bulk optimisation.
- Confirm that saved alt text remains correct.
- Test any custom integration.
- Check error logs.
- Record the results.
Avoid relying on private implementation details unless you are prepared to maintain the integration whenever those details change.
If an integration depends on a specific class, function, database field, or internal method, document that dependency clearly.
14. Diagnosing Custom Integration Failures
When a custom integration stops working, separate the problem into the following areas.
| Area | Questions to investigate |
|---|---|
| Configuration | Are the required settings present and correct? |
| Permissions | Does the current user have the necessary capability? |
| Product selection | Are the intended products being selected? |
| Image selection | Is the correct attachment being identified? |
| AI request | Is the provider request successful? |
| Response handling | Is the returned text being interpreted correctly? |
| Saving | Is the correct attachment metadata being updated? |
| Display | Does the public page output the expected alt text? |
| Compatibility | Did a software update change the relevant behaviour? |
| Security | Are requests validated and credentials protected? |
Test each stage independently wherever possible.
For example, if a generated description is correct but the wrong image is updated, the AI provider may be working correctly. The problem is more likely to involve product-to-attachment mapping or the saving workflow.
15. A Safe Development and Testing Procedure
Use the following process when building a custom integration around SmartDescribe Pro.
Stage 1 — Define the requirement
Write down exactly what the integration must do and which users need it.
Stage 2 — Inspect the installed version
Check the plugin’s actual source code and documentation. Confirm which features and extension points exist.
Stage 3 — Choose the least invasive design
Prefer existing settings and documented interfaces over direct source-code modifications.
Stage 4 — Build on staging
Do not begin experimental development on a live store.
Stage 5 — Test representative products
Include products with missing images, existing alt text, multiple images, and shared attachments where relevant.
Stage 6 — Test failure handling
Check what happens when the AI provider returns an error, a product is unavailable, or WordPress cannot save the result.
Stage 7 — Test permissions
Confirm that users without the required permissions cannot perform restricted operations.
Stage 8 — Test performance
Use a realistic product selection and monitor errors, request volume, and execution time.
Stage 9 — Document the integration
Record dependencies, configuration, known limitations, and recovery procedures.
Stage 10 — Plan maintenance
Review the integration after updates to WordPress, WooCommerce, SmartDescribe Pro, or the AI provider.
16. Frequently Asked Questions
Does SmartDescribe Pro provide a public developer API?
Do not assume that a public API is available. Check the documentation for your installed version or obtain confirmation from the plugin developer before building an integration around an API endpoint.
Can I add custom buttons to the SmartDescribe Pro interface?
Possibly, depending on the available documented extension points and the requirements of the custom feature. Verify the installed version before implementing interface changes.
Can I automatically optimise products when they are created?
This depends on whether the installed version supports the required workflow or exposes a suitable extension point. Any custom automation should handle incomplete products, missing images, permissions, provider errors, and API costs.
Can I update alt text using a separate custom plugin?
Yes, WordPress supports custom plugins that work with attachment metadata. However, the implementation must identify the correct image attachments and preserve existing data where appropriate.
Can I integrate SmartDescribe Pro with a custom reporting dashboard?
A custom dashboard may be possible if the required information can be accessed through documented or verified interfaces. First establish which data is available and how it is stored.
Should I edit SmartDescribe Pro’s PHP files directly?
Generally, no. Prefer documented extension points or a separate custom plugin. Direct modifications can be overwritten by updates and may complicate support.
Can custom code bypass the plugin’s normal settings?
Technically, custom code may alter a workflow, but bypassing established configuration and validation can introduce security, compatibility, and reliability problems. Use the plugin’s supported configuration wherever possible.
How can I confirm that a custom integration is safe to deploy?
Test it on staging, verify permissions, check error handling, confirm the correct attachment is updated, review logs, and test recovery procedures before deployment.
17. Developer Integration Checklist
Before releasing a custom integration, confirm that:
- The business requirement is clearly defined.
- The installed SmartDescribe Pro version has been inspected.
- Required hooks, APIs, or internal interfaces have been verified.
- The integration uses the least invasive suitable approach.
- Product IDs and image attachment IDs are handled correctly.
- Existing alt text is preserved according to the intended workflow.
- Shared image attachments are handled deliberately.
- API keys remain private.
- User permissions are checked.
- Inputs are validated and outputs escaped appropriately.
- API failures and saving errors are handled.
- Bulk operations are tested at a realistic scale.
- Performance and API costs have been considered.
- The integration has been tested on staging.
- Dependencies and maintenance requirements are documented.
- A backup and recovery plan is available.
18. Final Recommendations
SmartDescribe Pro can be part of a wider WooCommerce workflow, but reliable customisation starts with understanding the boundaries between the plugin, WordPress media attachments, WooCommerce products, the AI provider, and the public-facing website.
Use built-in settings where possible. When additional behaviour is required, verify the installed version’s documented extension points before writing custom code. Avoid undocumented assumptions, protect existing alt text, and test changes on staging.
The guiding principle for developers is simple: extend verified functionality, preserve WordPress data integrity, protect credentials, and make every custom workflow testable and maintainable.