Media Entity Instagram
Provides Instagram integration for Drupal Media, allowing you to embed Instagram posts as media entities using Facebook's Graph API.
media_entity_instagram
Install
composer require 'drupal/media_entity_instagram:^4.0'
composer require 'drupal/media_entity_instagram:^3.0'
Overview
Media Entity Instagram is a media source provider module that integrates Instagram content into Drupal's core Media system. It enables site builders to create a dedicated Media Type for Instagram posts, which can then be embedded throughout the site using Drupal's media management capabilities.
The module leverages Facebook's oEmbed API (via the Graph API) to fetch Instagram post metadata and HTML embed code. This approach ensures proper rendering of Instagram posts with their original styling and interactivity. Since Instagram's API is now part of Facebook's ecosystem, the module requires Facebook Developer credentials (App ID and App Secret) to function.
Key capabilities include automatic metadata extraction (author name, shortcode), customizable embed display with caption visibility options, and seamless integration with Drupal's Media Library for easy content selection and insertion.
Features
- Creates an Instagram media source plugin that extends Drupal's oEmbed system for handling Instagram posts and IGTV content
- Provides dedicated field formatter (Instagram embed) with options to control maximum width and caption visibility
- Integrates with Drupal's Media Library, providing a custom add form for easily adding Instagram content
- Extracts metadata from Instagram URLs including shortcode, author name, thumbnail, and embed HTML
- Supports multiple Instagram URL formats including instagram.com/p/, instagr.am/p/, instagram.com/tv/, and instagr.am/tv/
- Includes JavaScript integration for processing Instagram embeds and rendering them properly on the frontend
- Automatically creates and configures source fields when setting up a new Instagram media type
Use Cases
Embedding Instagram posts in content
Content editors can add Instagram posts to articles by creating Instagram media entities. Simply paste an Instagram post URL (e.g., https://instagram.com/p/ABC123) when creating media, and the post will be embedded with full interactivity including likes, comments, and profile links.
Building social media feeds
Site builders can create views of Instagram media to display curated social media feeds. Combined with other social media modules, this enables comprehensive social media integration on the site.
Media Library integration for WYSIWYG
When using CKEditor with Media Library, editors can insert Instagram embeds directly into rich text fields through the familiar Media Library dialog, maintaining consistent content management workflows.
IGTV video embedding
The module supports IGTV URLs (instagram.com/tv/) in addition to regular posts, allowing sites to embed longer-form Instagram video content alongside standard posts.
Tips
- Create your Facebook App at developers.facebook.com and enable the oEmbed Read feature to get your credentials
- The module supports both instagram.com and the shorter instagr.am URL formats
- Use the 'Hide caption' formatter option when you want to display only the visual content without the original post text
- Source fields for Instagram media can be either plain text or link fields, giving flexibility in how URLs are stored
Technical Details
Admin Pages 1
/admin/config/media/instagram-settings
Configure Facebook API credentials required for fetching Instagram content via the oEmbed API. These credentials authenticate requests to Facebook's Graph API which handles Instagram embed data.
Hooks 1
hook_oembed_resource_url_alter
Alters the oEmbed resource URL for Instagram requests. This hook modifies the URL to use Facebook's Graph API endpoint and appends the required access token (composed of App ID and App Secret).
Troubleshooting 4
Navigate to /admin/config/media/instagram-settings and enter your Facebook App ID and App Secret. These credentials must be from a Facebook Developer app with oEmbed API access enabled.
Ensure the Instagram media type's display is configured to use the 'Instagram embed' formatter. Check the view display settings at /admin/structure/media/manage/[type]/display.
Verify your Facebook App is properly configured in the Facebook Developer Portal with the oEmbed Read permission. Check that your app is not in Development mode if you need production-level access.
This is a known limitation. Instagram embeds may not fully render in CKEditor's iframe preview but will display correctly on the published page.
Security Notes 2
- The Facebook App Secret is stored in Drupal configuration. Ensure your configuration is not exported to public repositories.
- The module is covered by Drupal's security advisory policy, ensuring security issues are handled through the official Drupal security process.