プッシュアイコン設定ガイド

このドキュメントは、通知バーの小アイコン、右側のアイコン、大画像の設定方法をユーザーに案内することを目的としています。 alt text

📱 iOS アイコン設定方法

小アイコンの設定

Images.xcassets-AppIcon に移動し、以下の寸法で iPhone Notification アイコンを設定します：

40 x 40px
60 x 60px

alt text

右側のアイコン / 大画像の設定

✅ 対応バージョン

EngageLab iOS SDK v3.0.0 から iOS 10 以上でサポート。

🧑‍💻 クライアント設定

Service Extension サービスを作成します。
mtpush-extension-ios-xxx.xcframework ファイルを Service Extension プロジェクトに追加します。
以下の2つのフレームワークを追加します：
- libz.tbd
- libresolv.tbd
[mtpushSetAppkey:] メソッドを呼び出して AppKey を設定します（AppPush アプリケーション作成時に使用した AppKey と一致していることを確認してください）。
[didReceiveNotificationRequest:] コールバック内で画像リンクを取得します。以下は例のコードです：

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { self.contentHandler = contentHandler; self.bestAttemptContent = [request.content mutableCopy]; self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [NotificationService]", self.bestAttemptContent.title]; NSString * attachmentPath = self.bestAttemptContent.userInfo[@"my-attachment"]; // 存在する場合 if (attachmentPath) { // ダウンロード NSURL *fileURL = [NSURL URLWithString:attachmentPath]; [self downloadAndSave:fileURL handler:^(NSString *localPath) { if (localPath) {UNNotificationAttachment * attachment = [UNNotificationAttachment attachmentWithIdentifier:@"myAttachment" URL:[NSURL fileURLWithPath:localPath] options:nil error:nil]; self.bestAttemptContent.attachments = @[attachment]; } [self apnsDeliverWith:request]; }]; }else{[self apnsDeliverWith:request]; } } - (void)downloadAndSave:(NSURL *)fileURL handler:(void (^)(NSString *))handler { NSURLSession * session = [NSURLSession sharedSession]; NSURLSessionDownloadTask *task = [session downloadTaskWithURL:fileURL completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) { NSString *localPath = nil; if (!error) {NSString * localURL = [NSString stringWithFormat:@"%@/%@", NSTemporaryDirectory(),fileURL.lastPathComponent]; if ([[NSFileManager defaultManager] moveItemAtPath:location.path toPath:localURL error:nil]) {localPath = localURL;} } handler(localPath); }]; [task resume]; }

              
              - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
  self.contentHandler = contentHandler;
  self.bestAttemptContent = [request.content mutableCopy];
  self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [NotificationService]", self.bestAttemptContent.title];
  
  NSString * attachmentPath = self.bestAttemptContent.userInfo[@"my-attachment"];
  // 存在する場合
  if (attachmentPath) {
    // ダウンロード
    NSURL *fileURL = [NSURL URLWithString:attachmentPath];
    [self downloadAndSave:fileURL handler:^(NSString *localPath) {
      if (localPath) {UNNotificationAttachment * attachment = [UNNotificationAttachment attachmentWithIdentifier:@"myAttachment" URL:[NSURL fileURLWithPath:localPath] options:nil error:nil];
        self.bestAttemptContent.attachments = @[attachment];
      }
      [self apnsDeliverWith:request];
    }];
  }else{[self apnsDeliverWith:request];
  }
}

- (void)downloadAndSave:(NSURL *)fileURL handler:(void (^)(NSString *))handler {
  NSURLSession * session = [NSURLSession sharedSession];
  NSURLSessionDownloadTask *task = [session downloadTaskWithURL:fileURL completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) {
    NSString *localPath = nil;
    if (!error) {NSString * localURL = [NSString stringWithFormat:@"%@/%@", NSTemporaryDirectory(),fileURL.lastPathComponent];
      if ([[NSFileManager defaultManager] moveItemAtPath:location.path toPath:localURL error:nil]) {localPath = localURL;}
    }
    handler(localPath);
  }];
  [task resume];
}

このコードブロックはフローティングウィンドウ内に表示されます

🌐 サーバー側設定

ios の下で mutable-content と extras フィールドを設定します：

フィールド名	型	必須	親フィールド	説明
`mutable-content`	boolean	任意	`notification.ios`	通知拡張を有効にします。iOS 10 の `UNNotificationServiceExtension` をサポートするには `true` に設定します。
`extras`	JSON オブジェクト	任意	`notification.ios`	追加フィールド。キー（例：`my-attachment`）はクライアントコードと一致している必要があります。

JSON の例:

"notification": { "ios": { "alert": { "title": "title", "subtitle": "subtitle" }, "mutable-content": true, "extras": { "my-attachment": "https://raw.githubusercontent.com/Tikon/imgRepo/master/ic_launcher.png" } } }

              
              "notification": {
  "ios": {
    "alert": {
      "title": "title",
      "subtitle": "subtitle"
    },
    "mutable-content": true,
    "extras": {
      "my-attachment": "https://raw.githubusercontent.com/Tikon/imgRepo/master/ic_launcher.png"
    }
  }
}

このコードブロックはフローティングウィンドウ内に表示されます

🤖 Android アイコン設定方法

✅ 対応バージョン

EngageLab Android SDK v4.4.0 からサポート。

📡 チャンネルサポート

チャンネル	動的小アイコン	右側のアイコン	大画像
EngageLab	✅ (システムサポート)	✅ (Meizuを除く)	✅ (システムサポート)
Xiaomi	❌	❌	❌
Huawei	✅	✅ (サービス/情報)	❌
Honor	❌	✅ (マーケティング非対応)	❌
OPPO	❌	✅	✅
FCM	❌	✅	✅
Meizu	❌	❌	❌
vivo	❌	❌	❌

📝 注意事項:

OPPO: プッシュ対象が20を超え、ColorOSバージョンが5.0以上の場合、WiFi環境で最初の通知に大画像が表示されます。

Xiaomi: 2023年8月時点で、動的アイコンおよび大画像設定はプッシュ時にサポートされなくなりました。

🎨 小アイコンの設定

🧑‍💻 クライアント設定

プロジェクトに res/drawable/mtpush_notification_icon リソースが含まれている場合、デフォルトアイコンとして使用されます。
このリソースが存在しない場合、アプリケーションアイコンがデフォルトで使用されます。

FCM チャンネル設定例:

              
              <meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/mtpush_notification_icon" />
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />

このコードブロックはフローティングウィンドウ内に表示されます

🌐 サーバー側設定

フィールド名	型	必須	親フィールド	説明
`small_icon`	string	任意	`notification.android`	ネットワークアイコンリンクまたは画像リソースパス、サイズは300kを超えないこと
`small_icon_uri`	string	任意	`options.third_party_channel.vendor`	ベンダーチャンネルアイコンスタイル、現在はHuaweiのみサポート

JSON の例:

"notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "small_icon": "logo" } }, "options": { "time_to_live": 60, "third_party_channel": { "huawei": { "distribution_new": "pns_mtpush", "small_icon_uri": "https://res.engagelab.net/oversea/e/website/2025/_nuxt/app-push.II1rRaB5.webp" } } }

              
              "notification": {
  "android": {
    "alert": "Hi, Push!",
    "title": "Send to Android",
    "small_icon": "logo"
  }
},
"options": {
  "time_to_live": 60,
  "third_party_channel": {
    "huawei": {
      "distribution_new": "pns_mtpush",
      "small_icon_uri": "https://res.engagelab.net/oversea/e/website/2025/_nuxt/app-push.II1rRaB5.webp"
    }
  }
}

このコードブロックはフローティングウィンドウ内に表示されます

🖼️ 右側のアイコン / 大画像の設定

🌐 サーバー側フィールド説明

フィールド名	型	必須	親フィールド	説明
`style`	int	任意	`notification.android`	通知バーのスタイルタイプ：デフォルト0、`1=bigText`、`2=Inbox`、`3=bigPicture`
`big_pic_path`	string	任意	`notification.android`	`style=3` の場合に有効。URLまたはローカルパスを設定可能
`large_icon`	string	任意	`notification.android`	右側のアイコン、ネットワーク画像または `drawable` リソースパス、サイズは300kを超えないこと

JSON の例:

{ "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "large_icon": "logo", "big_pic_path": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg", "style": 3 } }, "options": { "third_party_channel": { "huawei": { "distribution_new": "pns_mtpush", "large_icon": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg" } } } }

              
              {
  "notification": {
    "android": {
      "alert": "Hi, Push!",
      "title": "Send to Android",
      "large_icon": "logo",
      "big_pic_path": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg",
      "style": 3
    }
  },
  "options": {
    "third_party_channel": {
      "huawei": {
        "distribution_new": "pns_mtpush",
        "large_icon": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg"
      }
    }
  }
}

このコードブロックはフローティングウィンドウ内に表示されます

❓ FAQ

小アイコン関連の問題

1. グレー表示される？

ネイティブ Android 5.0 以上で、アプリの targetSdkVersion が 21 以上の場合、通知小アイコンにシステムが強制的にマスクカラーを適用し、グレー表示されることがあります。輪郭と認識性を確保するため、影、グラデーション、背景のない中空アイコンを使用し、mtpush_notification_icon として名前を付け、プロジェクトの res/drawable ディレクトリ内の同名ファイルを置き換えることを推奨します。また、res ディレクトリ内の通知アイコン関連のすべてのアイコンファイル（例：drawable-xxhdpi など）を新しいアイコンリソースで統一的に置き換えてください。適切に設定した後、システムは準拠したグレー輪郭アイコンを表示し、異常または不明瞭なアイコンの問題を回避します。
一部のシステム（例：OnePlus 携帯、Android 10 の Google 携帯）では解決できない制限があります。
Xiaomi 携帯のランチャーはアイコンをキャッシュする場合があります。上記の要件に従って設定した後、携帯を再起動して再テストしてください。
Xiaomi 携帯では、EngageLab チャンネルまたは Xiaomi チャンネルを使用する場合、ネイティブスタイルに切り替える必要があります。切り替え方法は以下の通りです：

2. アイコン変更が反映されない？

システムまたはベンダーサービスがアイコンをキャッシュする可能性があります（Xiaomi や Meizu 携帯で発生する場合があります）。
アプリをアンインストールし、携帯を再起動してから新しいバージョンを再インストールすることを推奨します。

右側のアイコン / 大画像関連の問題

アイコン/画像が表示されない？

EngageLab チャンネル: デフォルトの通知バーのスタイルビルダーインターフェースが呼び出されているか確認してください。呼び出されている場合はインターフェースを削除し、アプリをアンインストールして再試行してください。
APNs (iOS): 右側のアイコンと大画像は同じ画像です。フォアグラウンドでは通知ドロップダウンに大画像が表示され、その他の場合は右側のアイコンのみが表示されます。
FCM (Android): 展開前は右側のアイコンが表示され、展開後は大画像が表示されます。