Shopping Cart
Key features and benefits
- Official Instagram API: the module uses the Instagram API with Instagram Login and the
instagram_business_basicpermission. It does not use the Instagram Legacy API or Instagram Basic Display API interfaces discontinued by Meta. - No requests to Instagram when displaying the page: the block is built from posts saved in the store database. Displaying the page does not trigger requests to Instagram, and synchronisation takes place in separate requests.
- Photos served from the store domain: images are saved in the
img/pdblockinstagram/directory. The block does not load Instagram scripts, frames, or cookies, and when it is displayed, the customer's browser does not connect to Meta servers. - Automatic token renewal: the module renews the token roughly every 7 days during synchronisation, so with a working CRON or store traffic, there is no need to generate it again.
- Failure resilience: when Instagram is unavailable, rejects the token, or limits the number of requests, customers still see the most recently saved posts. A failed synchronisation never removes a working feed.
- Configurable appearance: grid or carousel, number of columns for desktop and mobile, spacing, square tiles, caption on hover, post preview, and a “Show more” button.
- Diagnostics panel: a header with status indicators, five tabs, a preview of saved posts, server check, and event log make configuration and troubleshooting easier.
How does the module work?
- Account connection: in the Connection tab, you paste the token generated in Meta for Developers. The module verifies it, reads the account name, and immediately fetches posts.
- Server-side synchronisation: the module fetches the profile and the list of posts, and downloads photos only for posts that are not yet in the store. It stores the 48 most recent posts from the account.
- Local copies of photos: each photo is decoded and re-saved as a JPEG in two widths, 640 px and 320 px. Files for posts outside the latest 48 are deleted.
- Display in the store: the page shows saved posts. If the feed is outdated, after the page loads, the browser sends one background request to the store, which starts synchronisation.
If the account does not yet have any saved posts, the block is not displayed. The main Show feed switch enables and disables all display locations at once.
Block appearance and content settings
| Setting | Options | Default |
|---|---|---|
| Layout | Grid or single-row carousel, scrollable by swipe or arrows. | Grid |
| Number of posts | From 1 to 48. | 8 |
| Desktop columns | From 2 to 8 (screens from 992 px). On tablets (768–991 px), the module shows the same number of columns, up to a maximum of 4. | 4 |
| Mobile columns | 1, 2, or 3 (screens below 768 px). | 2 |
| Spacing between photos | 0, 2, 4, 8, 12, 16, or 24 px. | 8 px |
| Square tiles | Crop photos to a square, like in the Instagram profile grid, or keep the original aspect ratio. | Enabled |
| Caption on hover | The beginning of the post caption (up to 90 characters) on the photo when hovered, or no caption. On touch screens, the overlay is not shown. | Beginning of caption |
| Clicking a post | Open the preview in the store or the post on Instagram in a new tab. | Preview in the store |
| “Show more” button | Only in grid layout: reveals additional batches of posts, up to four times more than the set number, with a maximum of 48. | Disabled |
| Block title | Separate for each language, up to 128 characters. An empty title is not displayed. | “Follow us on Instagram” |
| Profile link | Profile photo, @account name, and “Follow” button linking to the Instagram profile. | Enabled |
| Videos and reels | Include or skip video posts and reels. | Included |
| Only posts containing | Text up to 64 characters, for example a hashtag. Only posts whose caption contains this text are displayed, regardless of letter case. | Empty (all posts) |
Video and reel tiles have a play icon, and posts with multiple photos have a carousel icon. Appearance settings are saved separately for each store, store group, or all stores.
Where can Instagram photos be displayed?
- Homepage: in the homepage content (hook
displayHome). - Product page: below the product details (hook
displayFooterProduct). - Above the footer on every page: hook
displayFooterBefore. - Anywhere in the theme: the
{widget name='pdblockinstagram'}code pasted into a template. Optionallimitandlayoutparameters let you set a different number of posts and layout, for example{widget name='pdblockinstagram' limit=6 layout='carousel'}. The code to copy is available on the Dashboard.
The module stylesheet and script are included only on pages where an enabled display location shows the feed; a block inserted with the widget includes them on its own. In the Hummingbird theme, the default for PrestaShop 9, the block width on the homepage and above the footer is adjusted to the theme container.
Post preview window in the store
After clicking a photo, a window opens with an enlarged image, publication date, full post caption, and a View on Instagram button. You can move between posts using the arrows in the window or the arrow keys on the keyboard. The window closes with the Close button, the Esc key, or a click on the background, and focus returns to the clicked photo.
Without JavaScript or in a browser without dialog support, each tile remains a regular link to the post on Instagram. For videos and reels, the preview shows the cover image, and for carousels, the first photo; the video can be watched on Instagram.
Synchronisation: CRON, background refresh, and panel button
- Frequency: new posts are fetched every 15 min, 30 min, 1 h, 3 h, 6 h, 12 h, or 24 h. By default, every hour.
- CRON: the CRON and diagnostics tab provides the address with a secret key and a sample crontab line. It is recommended to call the address every 15–60 minutes using GET or POST. The module performs work only when it is time for synchronisation or token renewal; the
&force=1parameter forces synchronisation. - Background refresh without CRON: when a customer opens a page with an outdated feed, the browser sends one POST request to the store one and a half seconds after the page loads, at most once per minute in one browser tab. The page always shows saved posts, so the customer never has to wait.
- Panel button: Synchronise now fetches posts immediately, regardless of the schedule.
- Only one synchronisation at a time: a lock in the MySQL database prevents parallel synchronisations of the same account.
- Time limit: downloading photos in one run takes no more than 25 seconds. Remaining photos are downloaded on the next CRON call or background refresh, possible after about a minute.
Access token renewed automatically
The token generated in the Meta panel is valid for 60 days. The module renews it during synchronisation roughly every 7 days, and earlier when less than 14 days remain before expiry. According to Meta documentation, automatic renewal takes place no earlier than 24 hours after connection or the previous renewal; after a failed attempt, the module retries after one day. On the Dashboard and in the Connection tab, there is also a Refresh token now button, and the panel header shows the number of valid days remaining.
The token is stored in the store database and used exclusively by the server. It is never sent to customers' browsers, in the panel it is visible only in shortened form (the first and last four characters), and in messages and the event log it is masked.
If Instagram rejects the token (it expired, app access was revoked, the account password was changed, or no synchronisation was performed for 60 days), the module stops sending requests, shows a message in the panel, and continues to display saved posts. You only need to generate a new token and paste it using the Check and replace token button.
Photos saved on the store server
- Two sizes: each photo is saved as a progressive JPEG with widths of 640 px and 320 px; smaller originals are not enlarged. The profile photo has a width of 150 px.
- Secure downloading: photos are downloaded over HTTPS only from Instagram servers (
cdninstagram.com,fbcdn.net), then decoded and re-saved by PHP GD. Only image pixels are written to disk. The module requests JPEG format from Instagram servers; PNG and WebP files are converted if the GD library on the server supports them. - Durability: the
img/pdblockinstagram/directory is outside the module directory, so updating the module does not remove photos. - Image attributes:
srcsetwith both widths andsizesadjusted to the number of columns,widthandheightdimensions, lazy loading, and alt text from the beginning of the post caption (up to 125 characters) or in the form “Post by @name on Instagram”. - Emoji in captions: post captions are saved in a way that is resistant to database connection encoding, so emoji display correctly also in PrestaShop 1.7.0–1.7.6.
Resilience to errors and Instagram limitations
- Retries with increasing delay: after an error, the next attempt takes place after 5 minutes, and the delay doubles up to 6 hours. After exceeding the request limit, the module waits at least one hour.
- Protection of a working feed: photos that could not be downloaded are retried during the next synchronisation. If no photo can be saved, the previous feed remains unchanged.
- Safe links: the address of each post is rebuilt in the form
https://www.instagram.com/p/…/(alsoreelandtv). An unusual address is replaced with a link to the profile. - Page stability: an error while building the block does not interrupt the display of the store page. Connections to Instagram have time limits, TLS certificate verification, and do not follow redirects.
Configuration panel
The panel header shows the module status in text and colour form: feed visibility, connected account, number of valid token days, time of the last synchronisation, number of saved posts, and the last CRON call. The configuration is divided into five tabs.
| Tab | Contents |
|---|---|
| Dashboard | First steps (until the account is connected), account card (account type, posts saved and available on Instagram, token validity, last and next synchronisation), synchronisation and token refresh buttons, preview of the 12 most recent saved posts with hidden posts greyed out by filters, list of display locations, and widget code. |
| Connection | Pasting and checking the token, replacing the token, disconnecting the account, and the list of stores where the account is displayed. |
| Appearance | Display locations, block appearance, and post selection (videos and reels, text filter). |
| How to get a token | Step-by-step instructions for Meta for Developers: requirements, app creation, adding an Instagram account, generating a token, information after connection, and solutions to common problems. |
| CRON and diagnostics | CRON address and sample crontab line, time of the last call, generating a new address, post fetch frequency, server check (cURL, GD, writable photo directory), deleting saved posts, and event log. |
The event log records account connections and disconnections, synchronisations with the number of posts, downloaded and failed photos, token renewals, and errors, as well as the event source: CRON, store page (in the background), or panel. The module stores the last 200 entries, and the log can be cleared.
Multistore, languages, and permissions
- Separate account and settings: each store, store group, or all stores can have its own Instagram account and its own block appearance. A store without its own values inherits them from the group or all-stores settings.
- Shared feed: stores displaying the same account use one shared set of posts, photos, and token.
- Employee permissions: an employee with access only to some stores changes only what is shown in their stores. Settings shared for all stores (CRON address, frequency, log) require access to every store, and disconnecting an inherited account in one store only hides it there.
- Languages: the block title is set separately for each store language. The module interface and store texts are available in Polish and English.
Update from version 1.x
Version 1.x used the Instagram Legacy API, which Meta discontinued in June 2020, so since then it has not displayed photos. Version 2.0.0 was written from scratch. The update preserves the number of photos, caption setting, “Show more” button, and display on the homepage and product page. Old access data, hashtag feed, old scripts, and the header image option are removed, and the account must be reconnected with a new token.
Requirements and scope of operation
The declared compatibility range includes PrestaShop 1.7.0–9.x and PHP 7.0–8.5. The module was tested on PrestaShop 1.7.2.4, 1.7.4.4, 1.7.5.2, 1.7.6.7, 1.7.7.8, 1.7.8.11, 8.0.1, 8.1.5, 8.2.3, 9.0.2, and 9.1.5, with the Classic and Hummingbird themes. The front end works without jQuery; the script is about 12 KB and the stylesheet about 11 KB before compression.
- Server: PHP cURL and GD extensions, writable
img/pdblockinstagram/directory, and the ability to make outgoing HTTPS connections tograph.instagram.comand Instagram image servers. - Instagram: a professional account (business or creator); switching a private account is free. To create an app in Meta for Developers, a Facebook account is required, but a Facebook page is not required. According to the instructions in the panel, for reading your own account, the app can remain in development mode, without verification by Meta.
The module only reads posts from the connected account and does not publish anything to Instagram. Each store displays posts from one connected account. The API used does not provide hashtag search, so the module does not show posts from other accounts; the “Only posts containing” filter works on captions of your own posts. Stories are not available in the API, and for some reels with licensed music, Instagram does not provide an image, so such posts are skipped. Videos and reels are not played in the store, and posts with multiple photos are represented by the first photo.